Software of the Month Club 1996 June/Software of the Month Club 1996 June.iso/pc/dos/dtp/aurora/language.dox

Text File | 1995-02-24 | 172.3 KB | 4,447 lines

  The Aurora Macro Language Reference
  ───────────────────────────────────
  This Reference describes the Aurora Macro Language (AML). For a
  complete description of all builtin and library functions, see the AML
  Function Reference. For information on how to install, configure, and
  use Aurora, see the Aurora Editor Users Guide.

  If you are viewing this document with Aurora, you can use the
  'Language Reference Topics' popup menu on the Help menu <f1> to jump
  quickly to any topic in the document.

  To transfer to the full AML Function Reference: move the cursor to a
  function name or statement keyword in this reference document and
  press <shift f2>. Note that most extension functions are not
  documented in the AML Function Reference.

  ──────────────────────────────────────────────────────────────────────
  Copyright (C) 1995 by nuText Systems.  All rights reserved worldwide.
  No parts of this document may be copied in part or in whole, except as
  provided in the License in the accompanying documentation.
  ──────────────────────────────────────────────────────────────────────


  Introduction
  ────────────
  The Aurora Macro Language (AML) is the native macro language of The
  Aurora Editor. AML is a flexible, interpreted computer language which
  is easy-to-use, yet powerful and rich in function. Understanding the
  macro language can help you to:

    - Tailor the day-to-day operation of the editor to your own
      preferences
    - Modify or add to existing editor functions
    - Create new editor functions
    - Customize detailed aspects of your editing environment

  A large base of macro language source and object code is shipped with
  the editor. You can modify the source code to suit your own
  preferences, or you can use the macro language to create your own new
  editor functions.

  Although it is easy to use the editor without understanding all the
  details of the macro language, knowledge of the macro language can
  give you a more complete understanding of how the editor actually
  works. Experienced users will find it to be an indispensable tool.


  Overview
  ────────
  If you browse the directory where the editor is installed, you will
  notice only one executable file: A.EXE. This executable file contains
  all of the builtin functions of the editor, as well as the macro
  language interpreter and compiler.

  With the interpreter and compiler both present within an edit session,
  macro language source code can be executed interactively. In fact,
  both the interpreter and the compiler are accessible as builtin
  functions within the macro language itself.

  Since the editor is written in its own macro language, it can be
  viewed as one large compiled 'macro' (contained in the file A.X). Much
  of the source code for this macro is shipped with the editor, allowing
  for a high degree of customization.

  Hundreds of builtin and user-defined functions are supplied for
  manipulating strings, files, text buffers, cursors, windows, and a
  large variety of other internal editor structures and features.

  AML also has powerful event-handling and object-oriented capabilities.
  Functions can be defined which respond to external, internal, and user
  defined events. Functions and variables can be encapsulated into
  objects, and objects can organized into object hierarchies with
  inheritance and multiple inheritance. Inheritance hierarchies can also
  be dynamically altered within a macro.

  To simplify macro development, the editor is also configured to
  provide compilation support for its own macro language. Macro source
  code can be compiled and executed within the editor. If compilation
  errors are found, the cursor is automatically moved to the appropriate
  location in the source code for corrections.


  The Syntax
  ──────────
  The macro language syntax includes a rich assortment of statements,
  operators, and functions which can be combined to form very simple or
  very complex expressions.

  In designing the macro language syntax, every effort was made to
  provide an attractive interface to the editor which is both powerful
  and easy-to-use. Those who are already familiar with other programming
  languages will find the syntax of AML similar to BASIC or Pascal, but
  with a simpler function call syntax.

  AML is also a 'typeless' language. The user need not be concerned with
  conversions from string to numeric data, or vice versa, and variable
  declarations are usually not required.


  Identifiers
  ───────────
  Identifiers are user-defined names which denote variables and
  functions. Valid identifiers may be composed of letters (a-z and A-Z),
  numeric digits (0-9), underscores (_), question marks (?), and the
  character (#). Identifiers cannot begin with a numeric character, and
  are always case sensitive. For example:

  These identifiers are valid:
    abc
    variable13
    _done?

  These identifiers are not valid:
    12twelve          // identifiers may not start with numeric digit
    bad variable      // identifiers may not include spaces
    variable!         // the '!' character may not be used


  Reserved Words
  ──────────────
  The following reserved words are used by the macro language for
  keywords and statements and cannot be used as identifiers for
  user-defined variables or functions:

    and        elseif     item       not        set        then
    break      end        key        object     setobj     until
    case       forward    keyword    or         setx       var
    databuf    function   loop       otherwise  setxfun    when
    define     if         menu       ref        setxobj    while
    do         if?        menubar    repeat     shl
    else       include    mod        return     shr

  Unlike the identifiers used for variables and functions, reserved
  words may be entered in mixed case.


  Strings
  ───────
  A string is a contiguous sequence of characters, up to a maximum
  length of 16000 characters. String constants must be enclosed in
  either single quotes (') or double quotes (") and the starting quote
  character must match the ending quote character. For example:

    "This is valid string"
    'This is also a valid string'
    "This is 'Ok'"
    'This is "Ok" too'

    "This is not a string'
       // quotes don't match

  A string with no characters is referred to as 'the null string':

    ''        // the null string
    ""        // the null string

  The backslash character (\) is used to indicate that the next
  character in the string is to be interpreted literally. It may be used
  to enclose quote characters (and the literal character itself) in the
  string. For example:

    '\''      // one single quote
    "\"\"'"   // two double quotes and a single quote

  If the backslash character (\) is used in a string, it must be
  preceded by another backslash character:

    '\\\\'              // a string containing two backslash characters
    "C:\\TXT\\ABC.TXT"  // a fully qualified filename


  Numbers
  ───────
  The macro language supports both decimal and hexadecimal integer
  constants. A decimal constant is a contiguous sequence of numeric
  digits. A hexadecimal constant is contiguous sequence of numeric
  digits or the letters A through F followed by the letter 'h' (the
  characters A through F and 'h' may be in mixed case). Both decimal and
  hexadecimal constants must begin with a numeric digit. For example:

    2   72   1234567     // valid decimal numbers
    0h  20h  0Dh  0ffH   // valid hexadecimal numbers

    ffh                  // invalid - must begin with a numeric digit

  All numbers must be within the range -2,147,483,648 to 2,147,483,647
  and must be integers.


  Spaces
  ──────
  To improve readability, spaces and lines many be inserted anywhere
  within your macro source code, as long as they are not inserted within
  reserved words, identifiers, multi-character operators, strings, or
  numbers. For example:

    a=2 b="a is two" if a==2 then say b end

  could be rewritten as:

    a = 2
    b = "a is two"

    if a == 2 then
      say b
    end


  Comments
  ────────
  Comments can make your source code much more descriptive and readable.
  AML supports both single-line and multi-line comments.

  To place a comment at the end of a single line, use the single-line
  comment delimiter '//'. In a single line comment, any characters
  located between the delimiter '//' and the end of the line will be
  ignored. For example:

    x = 2        // this is a single line comment

    // this is another single line comment
    y = 3

  Multi-line comments can span any number of lines. For multi-line
  comments, any characters located between the comment delimiters '/*'
  and '*/' are ignored. For example:

    x = 2  /* this is multi-line comment */  y = 3

    /* this is
       another
       multi-line
       comment */
    y = 3

  Multi-line comments cannot be nested.


  Variables
  ─────────
  A variable is an identifier which is associated with a value that can
  be changed during execution. Since AML is typeless, variables do not
  need to be defined with data types such as 'numeric', 'character', or
  'string'. The macro language compiler and interpreter will
  automatically handle these data types internally, based on the usage
  of the variable.

  Variables fall into three categories:

  Local variables:
    Local variables are defined only within the scope of a function
    definition and only have values while the function is executing.
    Local variables can only be referenced after they are defined and
    only from within the function in which they are defined. For
    example:
                        // variable 'a' is not defined here
      function xyz
        a = 1           // variable 'a' is local to function 'xyz'
      end
                        // variable 'a' is not defined here

  Global variables:
    Global variables are defined outside the scope of any function
    definition and only have values while the macro file in which they
    are contained is executing. Global variables can only be referenced
    after they are defined and only from within the macro source file in
    which they are defined.

    Global variables can be referenced from inside or outside the scope
    of a function definition. For example:

      g = 2             // 'g' is a global variable
      function xyz
        a = g           // 'g' is defined here, 'a' is local
      end
      g = 3             // 'g' is defined here

    If a reference is made to a variable from within a function and the
    variable name refers to both a local and a global variable, then the
    local variable always takes precedence.

  Object variables:
    Object variables are defined as they are used from any location
    within a macro. When an object variable is assigned a value, it
    continues to hold the value until it is assigned a new value, or the
    object in which it is contained is destroyed (see 'Objects').

    Object variables which are assigned a value in one macro file can be
    referenced in another macro file. In this sense, object variables
    are more persistent and have an even larger scope than global
    variables. Object variables can be referenced from any location
    within a macro and must usually be prefixed with an underscore
    character when referenced. For example:

      _abc = 2          // 'abc' is an object variable
      function xyz
        a = _abc        // 'abc' is defined here, 'a' is local
      end
      _abc = 3          // 'abc' is defined here


  The Assignment Statement
  ────────────────────────
  The assignment statement is used to change the value of a variable.
  Assignment statements use the following form:

    variable_name = expression

  where the variable 'variable_name' is assigned the value of
  'expression'. 'expression' may be a simple or complex macro language
  expression composed of numbers, strings, other variables, other
  expressions, function calls, or even other statements.

  A few simple examples of the assignment statement are:

    x = 2                        // sets the variable x to 2
    x = x + 3                    // sets the variable x to 5
    fruit = 'apple'              // sets the variable fruit to 'apple'
    fruits = fruit + " orange"   // sets the variable fruits to
                                 //    'apple orange'

  Object variables can also be assigned values by using the 'set'
  statement. For example, the following two statements are equivalent:

    _count = 1     // set object variable 'count' to 1
    set count 1    // set object variable 'count' to 1

  Note that the underscore (_) character is not required when an object
  variable is referenced in the first part of the 'set' statement.


  Variable Declarations
  ─────────────────────
  In most cases, variables are automatically declared the first time
  they are assigned a value, and variable declarations are not required.
  For example:

    function abc
      a = 1                // local variable, declaration not required
      say a                // displays '1'
    end

    xyz = 'Hello there!'   // global variable, declaration not required
    say xyz                // displays 'Hello there!'

  However, if a local or global variable is referenced before it is
  assigned a value, then it must first be declared with the 'var'
  keyword. The 'var' keyword defines the identifier which follows it as
  a variable name and initializes the value of the new variable to the
  null string. For example:

    var  xyz                   // global variable 'xyz' is declared
    say  xyz                   // displays nothing (the null string)

    function
      var a                    // local variable 'a' is declared
      repeat
        a = a + 1              // 'a' is referenced before assigned
      until a == 10
    end

  Object variables do not need to be declared. Since references to an
  object variable must be preceded by an underscore character (_), the
  compiler automatically recognizes object variables. If an object
  variable is referenced and has not yet been assigned a value, the
  value of the object variable is the null string. For example:

    say _objectvar             // displays nothing (the null string)

    _objectvar = 12
    say _objectvar             // displays 12


  Conversions
  ───────────
  Since the macro language is typeless, explicit conversion between data
  types is not required. If a string is specified where a number is
  expected, it is converted to a number as it is used. Similarly, if a
  number is specified where a string is expected, it is converted to a
  string. For example:

    x = "12" + "34"       // x is '46'
    x = 12 + "abc"        // x is '12abc'


  Expressions
  ───────────
  Expressions are simple or complex groups of numbers, strings,
  variables, function calls, statements, or other expressions joined
  together by zero or more macro language 'operators'. These are just a
  few examples of simple expressions:

    1
    abc
    x / 4
    "apples " + "oranges"
    x and y
    getlines - getrow

  Expressions may be enclosed in parentheses (called 'subexpressions')
  and joined by operators to form more complex expressions:

    (x + y) / 2
    ((a + b) * (b + c)) shl (c - d)
    (a or b) and ((not c) or d)

  The evaluation of expressions generally proceeds from left to right,
  but is also based on the priority of the operators within the
  expression, or the 'operator precedence'. Operators with higher
  precedence are evaluated before operators with lower precedence. For
  example, in the expression:

    x - y * 5

  'y * 5' is evaluated first and then subtracted from 'x', since the
  multiplication operator '*' has a higher precedence than the
  subtraction operator '-'. Parentheses may be used to force the
  expression to be evaluated with a user-defined priority. For example:

    (x - y) * 5

  In the above example, 'x - y' is evaluated first, and then multiplied
  by '5'.

  Note that while the value of an expression is always based on
  parentheses and operator precedence, the actual order in time in which
  elements of the expression are evaluated is not defined (the 'and' and
  'or' operators are exceptions - see 'Logical Operators') . For
  example:

    (funA 1) + (funB 2) * (funC 3)

  In the expression above, you may not assume that the function 'funC'
  is called before the function 'funA'.


  True and False
  ──────────────
  Several macro language operators and statements test whether an
  expression is TRUE or FALSE. An expression is FALSE if it is equal to
  zero or the null string. For any other values, the expression is TRUE.
  For example:

    x = 4   // x is TRUE
    x + 3   // value is TRUE
    x - 4   // value is FALSE
    x = ''  // x is FALSE


  Arithmetic Operators
  ────────────────────
  Arithmetic operators are used to perform simple integer arithmetic on
  numbers within expressions. The result of any arithmetic expression is
  always an integer in the range of -2,147,483,648 to 2,147,483,647. The
  arithmetic operators are:

    *    multiplication
    /    division
    mod  modulation
    +    addition
    -    subtraction (or unary negation)

  The division and mod operators perform an integer division. The
  division operator truncates any fractional result. The mod operator
  returns an integer remainder.

  Addition and subtraction have a lower precedence than multiplication
  and division. Unary negation has a higher precedence than than all the
  other arithmetic operators (and all other operators except the
  parentheses and substring operators).

  Examples:

    y = 5
    x = (6 + y * 3) / 2    // x is 10
    z = x mod 3            // z is 1


  Relational Operators
  ────────────────────
  Relational operators are used to compare two expressions. The result
  of evaluating a relational operator is always either TRUE (1) or FALSE
  (the null string). Relational operators have a lower precedence than
  arithmetic operators. The relational operators are:

    <    less than
    <=   less than or equal to
    >    greater than
    >=   greater than or equal to
    ==   equal to
    <>   not equal to

  Note that relational operators can be used to compare both numbers and
  strings. Strings are compared by testing the ASCII values of each
  character in the string from left to right (a case sensitive
  comparison).

  Examples:

    // numeric comparisons
    a = 4  b = 5
    a < b   a <> b  a == b - 1  // these expressions are TRUE
    a > b   a == b              // these expressions are FALSE
    x = a < b                   // x is assigned a value of '1'
    x = a == b                  // x is assigned the null string

    // string comparisons
    a = "abc"  b = "xyz"
    a < b   a <> b              // these expressions are TRUE
    a > b   a == b              // these expressions are FALSE
    x = a < b                   // x is assigned a value of '1'
    x = a == b                  // x is assigned the null string


  String Operators
  ────────────────
  String operators are used to perform string concatenation and
  substring operations on character strings. The result of evaluating a
  string expression is always a character string. The string operators
  are:

    +                concatenation
    [ expr ]         one-character substring
    [ expr : expr ]  multi-character substring

  The concatenation operator '+' is used to join two or more strings
  together. For example:

    a = "apples"
    b = "oranges"
    x = a + " and " + b        // x is 'apples and oranges'
    x = 4 + ' ' + a            // x is '4 apples'

  Since the concatenation operator '+' is identical to the addition
  operator '+', two numeric strings cannot be concatenated with '+'. In
  this case, addition takes precedence (AML is a typeless language):

    x = "13" + "12"            // x is 25
    x = "13" + 4               // x is 17

  To concatenate two or more numeric strings, use the 'concat' builtin
  function:

    x = concat "13" "12"       // x is "1312"

  The substring operator [] is used to return a portion of a string. If
  only one numeric operand is specified, then the substring operator
  references a one-character substring at the position in the string
  specified by the operand. For example:

    a = "apples"
    b = "oranges"
    x = a [1]                  // x is 'a'
    x = b [5]                  // x is 'g'
    n = 4
    x = b [n + 2]              // x is 'e'

  Specifying a position of zero references the last character in the
  string:

    a = "apples"
    x = a [0]                  // x is 's'

  If two numeric operands are specified separated by a colon, then the
  substring operator references a multi-character substring at the
  position in the string specified by the first operand for the length
  specified by the second operand. For example:

    a = "apples"
    b = "oranges"
    x = a [1:3]                // x is 'app'
    x = b [2:5]                // x is 'range'
    n = 3
    x = b [n - 1 : n + 2]      // x is 'range'

  Specifying a length of zero returns the remainder of the string,
  starting at the specified position:

    b = "oranges"
    x = b [2:0]                // x is 'ranges'

  Note that the [] operator is not limited to variables. The [] operator
  can also be used with constants, numbers, expressions, and function
  calls. For example:

    i = 2
    x = "oranges" [i : 5]              // x is 'range'
    x = 26381 [3 : i]                  // x is '38'
    x = ('oranges' + 'apples') [7:3]   // x is 'sap'
    x = getlines [0]                   // x is the last digit of the
                                       //   total number of lines in the
                                       //   current buffer


  Logical Operators
  ─────────────────
  Logical operators test whether or not expressions are TRUE or FALSE.
  The result of evaluating a logical operator is also either TRUE (1) or
  FALSE (the null string). The logical operators are:

    and  - tests if two expressions are TRUE
    or   - tests if at least one of two expressions is TRUE
    not  - tests if an expression is FALSE

  Examples:

    a = 4  b = 5
    a and b                       // value is TRUE
    a - 4 and b                   // value is FALSE
    a - 4 or b                    // value is TRUE
    a == 5 or b == 4              // value is FALSE
    not a                         // value is FALSE
    not (b - a - 1)               // value is TRUE

  The 'and' and 'or' operators have a lower precedence than the
  arithmetic and relational operators. For example:

    a == 4 and a == b - 1         // is equivalent to..
    (a == 4) and (a == (b - 1))

  The 'not' operator has a higher precedence than both the arithmetic
  and relational operators. For example:

    b = 3;
    a = not b + 1       // a is 1

  Note that the 'and' and 'or' operators do not always evaluate all the
  expressions they compare. Once the value of the logical expression is
  known, no further evaluation occurs. For example:

    (funA 1) or (funB 2)

  In the example above, if 'funA 1' is TRUE, the or-expression is TRUE
  and the function 'funB' is not called. Similarly:

    (funA 1) and (funB 2)

  In the above example, if 'funA 1' is FALSE, the and-expression is
  FALSE and the function 'funB' is not called.


  Bitwise Operators
  ─────────────────
  The bitwise operators can be used to manipulate or test individual
  bits in numeric expressions. Bitwise operators have a higher
  precedence than the 'and' and 'or' logical operators and a lower
  precedence than the relational operators. The bitwise operators are:

    shl   shift bits left
    shr   shift bits right
    &     bitwise and
    |     bitwise or
    ^     bitwise exclusive-or

  Examples:

    a = 3  b = 6     // a = 00000011 in binary, b = 00000110 in binary
    a shl 2          // value is 00001100 in binary, or 12 in decimal
    b shl 1          // value is 00000011 in binary, or 3 in decimal
    a & b            // value is 00000010 in binary, or 2 in decimal
    a | b            // value is 00000111 in binary, or 7 in decimal
    a ^ b            // value is 00000101 in binary, or 5 in decimal
    a & 0fh          // value is TRUE (the 5th bit is '1' in 'a')
    a = a | 4        // turns on the 3rd bit in 'a', a = 7
    a = a ^ 8        // toggles the 4th bit in 'a', a = 11


  Operator Precedence
  ───────────────────
  The following table shows the precedence of all macro language
  operators (lower level numbers have higher precedence):

  Level    Operator     Description
  ─────    ────────     ───────────
   1       ()           Subexpressions, function call
           []           Substring
   2       +            Unary plus
           -            Unary minus
           not          Logical negation
   3       *            Multiplication
           /            Division
           mod          Modulation
   4       +            Addition
           -            Subtraction
   5       shl          Bitwise shift left
           shr          Bitwise shift right
   6       <            Less than
           >            Greater than
           <=           Less than or equal to
           >=           Greater than or equal to
   7       ==           Equal to
           <>           Not equal to
   8       &            Bitwise AND
   9       ^            Bitwise XOR
  10       |            Bitwise OR
  11       and          Logical AND
  12       or           Logical OR
  13       =            Assignment


  Control Statements
  ──────────────────
  Macro language expressions and statements are normally executed
  sequentially from left to right and top to bottom. Control statements
  provide ways to alter this control flow. The following control
  statements are available:

    if elseif else end
    if?
    case when otherwise end
    while do end
    repeat until
    loop end
    break
    return

  The 'if', 'if?', and 'case' statements can also be used within
  expressions.


  If and If? Statements
  ─────────────────────
  The 'if' and 'if?' statements can be used to conditionally execute
  macro code based on whether or not an expression is TRUE or FALSE.

  The format of the 'if' statement is:

    if condition then
      expressions
    elseif condition then
      expressions
    elseif condition then
      .
      .
    else
      expressions
    end

  Both the 'elseif' and 'else' clauses are optional. The 'elseif' clause
  may be specified any number of times, but the 'else' clause can only
  be specified once. 'if' statements may also be nested.

  The 'if' statement evaluates each 'if' or 'elseif' condition
  expression until one condition evaluates to TRUE. If a TRUE condition
  is found, the expressions associated with that condition are
  evaluated. If no conditions are TRUE and an 'else' clause is
  specified, then the expressions within the 'else' clause are
  evaluated. For example:

    a = 4
    if a == 3 then
      say 'a is 3'
    elseif a == 4 then
      say 'a is 4'                     // displays 'a is 4'
    else
      say 'a is something else'
    end

  Note that 'if' statements may also be used as expressions. In this
  case, the value of the 'if' statement is the value of the last
  expression evaluated within the 'if' statement. For example:

    a = 4
    say  a + if a == 6 then   // displays '15'
               10
             else
               11
             end

  The 'if?' statement is a shorthand version of the 'if' statement. The
  format of the 'if?' statement is:

    if? condition then_expression else_expression

  where 'else_expression' is optional.

  The 'if?' statement evaluates the expression 'condition'. If the
  condition is TRUE, 'then_expression' is evaluated, otherwise
  'else_expression' is evaluated.

  The 'if?' statement is primarily intended for use within expressions,
  where it may be less cumbersome to use than the full 'if' statement.
  The previous example could be rewritten as:

    a = 4
    say  a + ( if? a == 6 10 11 )


  The Case Statement
  ──────────────────
  The 'case' statement can be used as a more convenient way to write a
  large 'if' statement. It compares the value of an expression to many
  other expressions.

  The format of the case statement is:

    case expression
      when when_expression
        expressions
      when when_expression
        expressions
      .
      .
      otherwise
        expressions
    end

  Both the 'when' and 'otherwise' clauses are optional. The 'when'
  clause may be specified any number of times, but the 'otherwise'
  clause can only be specified once. 'case' statements may be nested.

  The 'case' statement compares the value of the case expression to the
  value of each when_expression until they equal. If they are equal, the
  expressions associated with the matching 'when' clause are evaluated.
  If no 'when' clauses are equal to the case expression, then the
  expressions within the 'otherwise' clause are evaluated. 'when'
  expressions can also test for multiple values by separating them with
  commas. For example:

    a = 4
    case a
      when 3
        say 'a is 3'
      when 1, 2, 4
        say 'a is 1, 2, or 4'          // displays 'a is 1, 2, or 4'
      otherwise
        say 'a is something else'
    end

  Like 'if' statements, 'case' statements may also be used as
  expressions. The value of the 'case' statement is the value of the
  last expression evaluated within the 'case' statement. For example:

    x = 4
    x = case x
          when 1  'one'
          when 4  'four'
          when 7  'seven'
          otherwise
            'something else'
        end
    say x                              // displays 'four'


  Iterative Statements
  ────────────────────
  Iterative statements evaluate a series of expressions repeatedly,
  usually while a condition is TRUE or until a condition is TRUE. There
  are three iterative statements: while do/end, repeat/until, and
  loop/end.

  The 'while' statement evaluates a series of expressions repeatedly
  while another expression is TRUE. The format of the 'while' statement
  is:

    while while_expression do
      expressions
    end

  'while_expression' is always evaluated before the first iteration of
  the loop. For example:

    x = 10
    while x do
      x = x - 1             // count downward to zero
    end


  The 'repeat' statement evaluates a series of expressions repeatedly
  until another expression is TRUE. The format of the 'repeat' statement
  is:

    repeat
      expressions
    until until_expression

  'until_expression' is evaluated after the first iteration of the loop.
  For example:

    x = 1
    repeat
      x = x + 1             // count upward to 10
    until x == 10


  The 'loop' statement evaluates a series of expressions until a
  'break', or 'return' statement is executed. It is important that one
  of these statements is executed, otherwise the 'loop' statement will
  repeat forever. The format of the 'loop' statement is:

    loop
      expressions
    end

  Example:

    loop
      case getkey                    // wait for key
        when <esc>                   // <esc> exits the loop
          break
        otherwise
          say "you didn't press <esc>"
      end
    end

  Note that the <ctrl break> key can be used to force an immediate exit
  from any of the above loops, which may may be helpful when debugging
  macros. However, <ctrl break> should be used with care, since it may
  leave the editor in an unstable state.


  Other Control Statements
  ────────────────────────
  Two other control statements are provided: the 'break' statement, and
  the 'return' statement.

  The 'break' statement immediately forces an unconditional exit from
  any 'while', 'repeat', or 'loop' statement in which it is located.

  The 'return' statement immediately forces an unconditional exit from
  the macro or macro function in which it is located. The 'return'
  statement can also be used to return a value to a calling function by
  specifying an expression after the 'return' keyword. For example:

    function abc
      return                 // returns the null string to the
    end                      //   calling function

    function xyz
      a = 4
      b = 5
      return a + b           // returns '9' to the calling function
    end


  Function Calls
  ──────────────
  Perhaps the most common macro language statement is the function call
  statement. The function call statement transfers control to a
  function, passing optional user-defined arguments. When the function
  returns, execution resumes at the statement after the function call.
  The format of the function call statement is:

    function_name  argument1 argument2 argument3 ...

  'function_name' may be a builtin function or a user-defined function.
  Any number of user-defined arguments (depending on available stack
  space) can be passed to a function. Arguments are always evaluated
  from left to right. For example:

    say "Just one argument"   // one argument
    beep 400 x + 500          // two arguments
    delline                   // no arguments

  Since every function returns a value, function calls may be used
  anywhere in an expression. For example:

    x = getlines
      // call 'getlines' and place the result in variable x

    y = (pos 'i' astring) - 1
      // call pos with arguments 'i' and astring, subtract 1 from the
      //   result, and place the new result in variable y

    // beep if the functions 'up' and 'getlinelen' both return TRUE
    if (up 2) and getlinelen then
      beep 400 500
    end

  If a function call with one or more arguments is used within an
  expression, the entire function call should be enclosed in
  parentheses, otherwise operators in the expression may assume the
  function arguments as their operands. For example:

    str = "oranges"

    y = (pos 'g' str) + 1     // y is 6
    y = pos 'g' str + 1       // y is 5
    y = x + getrow + 1

  In the first example above, the function 'pos' is called with the
  arguments 'g' and the value of 'str', and 1 is added to the result. In
  the second example, 1 is concatenated to the value of 'str' and the
  result becomes the second argument to the function 'pos'. In the third
  example, there is no ambiguity and the function call 'getrow' does not
  need to be enclosed in parentheses.

  If an argument in a function call is also a function call, then the
  argument must be enclosed in parentheses. For example:

    markline 1 (getlines "abc")

  In the example above, the function call 'getlines "abc"' is the second
  argument to the function call 'markline'. If the function call
  'getlines "abc"' was not enclosed in parentheses, then it would become
  a second statement, and the first statement would become 'markline 1'.

  If an argument in a function call is an expression separated by
  operators or is not itself a function call, then the argument does not
  need to be enclosed in parentheses. For example:

    markline  y  b                       // no parens needed
    markline  y + 1   a + b - 1          // no parens needed
    markline  y + getrow + 1 (getlines)  // 1st arg doesn't need parens
    markline  (getrow)  y + getlines     // 2nd arg doesn't need parens


  Function Definitions
  ────────────────────
  The editor has hundreds of builtin functions such as 'markline' or
  'beep' which are predefined. Builtin functions may be used anywhere
  without any declarations or definitions.

  To define your own functions, you must use the 'function' statement.
  The 'function' statement allows you to organize chunks of macro code
  into a package which can referred to later with a function call, thus
  allowing you to reuse existing code. The format of the 'function'
  statement is:

    function functionname (arg1 arg2 ...)
      .
      <macro code>
      .
    end

  The argument list (arg1 arg2 ...) is optional. Note that 'function'
  statements cannot be nested.

  The 'function' statement defines the function 'functionname' and
  associates it with the <macro code> contained within the body of the
  function. For example:

    // define the function 'abc'
    function abc
      say "Hello World!"
    end

    // call function 'abc' (displays 'Hello World!')
    abc

  Functions may also be called before they are defined by using the
  'forward' keyword. The 'forward' keyword informs the compiler that the
  name which follows it is to be treated as a function name. For
  example:

    forward abc

    // call 'abc'
    abc

    // define the function 'abc'
    function abc
      say "Hello World!"
    end

  The 'forward' keyword must also be used to declare functions which are
  called in the current macro source file, but which are actually
  defined in external macro language object modules (.X files). The
  editor library functions in LIB.X are examples of such functions.
  The 'forward' declarations for library functions can be found in
  DEFINE.AML.


  Function Types
  ──────────────
  Although the macro language compiler views functions as being either
  'builtin' or 'user-defined', three types of editor functions are
  referred to in this document and are defined briefly here:

    Builtin functions: these are pre-defined functions which are native
      to the macro language.

    Library functions: these are pre-compiled user-defined functions
      contained in LIB.X. No source code is provided for these
      functions.

    Extension functions: these are user-defined functions contained in
      EXT.AML. Source code is provided for these functions.

  Builtin functions and Library functions are also documented in the AML
  Function Reference (FUNCTION.DOX).


  Passing Arguments to Functions
  ──────────────────────────────
  Arguments may be passed to user-defined functions and accessed as
  variables within the body of the function. Consider the format of the
  function statement:

    function  functionname  (arg1 arg2 ...)
      .
     <macro code>
      .
    end

  The optional argument list (arg1 arg2 ...) assigns names to any
  variables which may be passed to the function during a function call.
  Note that the argument list does not define how many variables must be
  passed to the function - this is defined by a call to the function.

  If fewer arguments are passed to the function than are defined in the
  argument list, the extra variables will be equal to the null string on
  entry to the function. For example:

    // define function 'abc' with one argument
    function abc (message)
      if message then
        say message
      else
        say "No message!"
      end
    end

    // call 'abc' with no arguments (displays "No message!")
    abc

  If more arguments are passed to the function than are defined in the
  argument list, the extra arguments will not be accessible by name
  within the function. However, these arguments can still be accessed
  with the 'arg' builtin function. The 'arg' builtin function takes one
  argument: the position of the argument in the argument list. For
  example:

    // define function 'xyz' with 1 argument
    // (obtain the second argument with the 'arg' function)
    function xyz (message)
      say message + (arg 2)
    end

    // call 'xyz' with 2 arguments (displays "Hello World!")
    xyz "Hello " "World!"

  If the 'arg' function is specified with no arguments (or the argument
  '0'), the number of arguments is returned. For example:

    // define the function 'countargs'
    function countargs
      say "The number of arguments is: " + (arg)
    end

    // call 'xyz' (displays "The number of arguments is: 4")
    countargs 5 7 32 3


  Passing Variables by Reference
  ─────────────────────────────
  Variables can also be passed 'by reference' to a function. When a
  variable is passed by reference and the variable is modified in the
  called function, it is also modified where it was called. This can be
  used to return more than one value from a function.

  To pass variables 'by reference' to a function, use the 'ref' keyword
  before the variable in the function call (not in the argument list of
  the function definition). Only local and global variables may be
  passed by reference (object variables cannot be passed by reference).
  For example:

    // the 'modify' function changes the values of its arguments
    function modify (c d)
      c = 13
      d = 14
    end

    function callmod
      a = 1
      b = 2
      modify  ref a  ref b         // pass 'a' and 'b' by reference
      say a + b                    // displays 27 (not 3)
    end


  Function Return Values
  ──────────────────────
  All function calls in AML return a value, including calls to builtin
  functions and calls to user-defined functions. Builtin functions have
  predefined return values. User-defined functions can return values by
  default or by using the 'return' statement. Functions can also use
  variables passed by reference to return multiple values (see: Passing
  Variables by Reference).

  If no 'return' statement is included in the definition of a
  user-defined function, the function will return the value of the last
  expression evaluated in the function 'by default'. For example:

    // define the function 'datetime'
    function datetime (date)
      if date then
        // the builtin function 'getdate' returns the current date
        getdate
      else
        // the builtin function 'gettime' returns the current time
        gettime
      end
    end

    // call 'datetime' (displays the current date)
    say (datetime 1)

  The 'return' statement forces an immediate return from a function (or
  an external macro file), and returns a value. Any number of return
  statements can be specified. The value returned is the value of the
  expression following the return statement. If no expression follows
  the 'return' statement, then the null string is returned. For example:

    // define the function 'testvar'
    function testvar (variable)
      if variable == 'null' then
        return
      elseif variable then
        return variable + 4
      else
        return 'variable is null'
      end
    end

    say (testvar)           // displays 'variable is null'
    say (testvar 'null')    // displays nothing (the null string)
    say (testvar 5)         // displays '9'


  Objects
  ───────
  Using objects can help you to organize your macro code at an even
  higher level than functions.

  A macro language object is a user-defined collection of functions,
  object variables, and even other objects, which all work together to
  handle a complex task. In many ways, a macro language object is very
  much like a mini-database with function definitions and object
  variables as database records. Each object is identified by an object
  name.

  Most of the macro code base installed with the editor is organized
  into objects. For example, there are separate objects for edit
  windows, file manager windows, and prompt windows. The object 'edit'
  contains functions and variables for manipulating edit windows and
  processing edit window events. Likewise, the object 'fmgr' contains
  functions and variables for manipulating file manager windows and
  processing file manager window events.


  Object Definitions
  ──────────────────
  When the editor is initially started from the DOS command line, a
  default object named 'a' is automatically created. The object 'a'
  contains all the builtin editor functions and becomes the 'current'
  object immediately after the editor is started.

  The 'current' object is the object where macro code is currently being
  executed. It is also where all newly-defined functions and object
  variables are placed. For example:

    function xyz (message)
      say message
    end

    _message = "Hello!"
    xyz _message

  If the above code is executed immediately upon starting the editor,
  the function 'xyz' and the object variable 'message' are both placed
  in the object 'a'.

  To create a new object or change the current object, use the 'object'
  statement. The format of the 'object' statement is:

    object  object_name  (parent1 parent2 ...)

  The object inheritance list (parent1 parent2 ...) is optional.

  The 'object' statement will create a new object if the specified
  object_name does exist. In either case, the specified object becomes
  the current object. For example:

    // create the new object 'hello'
    // ..and make it the current object
    object hello

      // add the function 'xyz' to object 'hello'
      function xyz (message)
        writestr message
      end

    // create the new object 'goodbye'
    // ..and make it current object
    object goodbye

      // add object variable 'message' to object 'goodbye'
      _message = "Goodbye!"

    // now object 'hello' already exists,
    // ..so change the current object to 'hello'
    object  hello

      // add object variable 'message' to object 'hello'
      _message = "Hello!"

      // call the function 'xyz' previously defined in object 'hello'
      xyz _message

  Note that the 'object' statement is not terminated by the 'end'
  keyword.


  Object Inheritance
  ──────────────────
  An object can 'inherit' the functions and object variables of other
  objects by specifying other objects in the inheritance list of the
  'object' statement. When functions and variables are inherited, they
  can be called and referenced just as if they were contained in the
  original object.

  Consider the format of the 'object' statement:

    object  object_name  (parent1 parent2 ...)

  The optional object inheritance list (parent1 parent2 ...) specifies
  the objects from which object_name may inherit functions and object
  variables. The inheritance list is set regardless of whether or not
  the object 'object_name' existed previously.

  The objects 'parent1', 'parent2', etc. become the 'parent' objects of
  'object_name'. The object 'object_name' is said to be descended from
  'parent1', 'parent2' etc., since it inherits the characteristics
  (functions and variables) of these objects.

  Consider the following example:

    // create the new object 'parent'
    object parent

      // add the object variable _message to object 'parent'
      _message = "Hello"

      // add the function 'xyz' to object 'parent'
      function xyz (message)
        writestr message
      end

    // create a new object named 'child' descended from object 'parent'
    object child (parent)

      // now call 'xyz' with the argument "Hello" (both the function
      // 'xyz' and the object variable 'message' are inherited from
      // the object 'parent')
      xyz _message

  Note that references to inherited functions and variables are
  completely transparent once the inheritance list has been set. In the
  example above, it appears that the function 'xyz' and the variable
  'message' actually reside in the object 'child'.

  Parent objects may also have inheritance lists. When a function or
  variable reference is made and the reference is not found in the
  current object, then the inheritance list hierarchy of the object is
  searched in a 'depth first' manner. This means that the first parent
  object in the inheritance list of the object is searched first, then
  the inheritance list of the first parent object, and so on. The second
  parent object is searched only when the entire inheritance hierarchy
  of the first parent object has been searched without resolving the
  reference.

  Note that builtin editor functions are always immediately accessible
  from within any object (inheritance lists are not searched).

  The builtin function 'objtype?' can be used to test the inheritance
  hierarchy or 'ancestry' of an object. For example:

    // tests if the current object is descended from the object 'edit'
    if objtype? "edit" then
      .
      .
    end


  Other Object Statements and Functions
  ─────────────────────────────────────
  There are several object statements which are useful for changing the
  value of an object variable. When using these statements, the
  underscore character (_) is not required when specifying the object
  variable to change.

  The 'set' statement changes the value of an object variable in the
  current object. Its effect is equivalent to the object variable
  assignment statement:

    set _variable 12
    set variable 12           // the underscore is not required

      ..are equivalent to:

    _variable = 12

  The 'setobj' statement can be used to change the value of an object
  variable in another object, without changing the current object:

    // sets the value of 'variable' to '12' in the object 'edit'
    setobj variable 12 "edit"

  The 'setx' and 'setxobj' statements can be used to change the value of
  an object variable whose name is not known at compile-time:

    count = 5

    // sets the value of 'variable5' to '12'
    setx "variable" + count  12

    // sets the value of 'variable5' to '12' in the object 'edit'
    setxobj "variable" + count  12  "edit"

  The 'lookup' function can be used to obtain the value of an object
  variable whose name is not known at compile time:

    count = 5
    setx "variable" + count  12
    say (lookup "variable" + count)   // displays '12'

  The lookup function can also be used to retrieve the value of an
  object variable which does not reside in the inheritance hierarchy of
  the current object:

    // displays the value of 'variable5' in the object 'edit'
    say (lookup "variable5" "edit")

  If the object variable is located in the inheritance hierarchy of the
  current object and its name is known at compile-time, then a simple
  variable reference is sufficient:

    // displays the value of 'variable5'
    say _variable5


  The following is a complete list of all the object functions:

    destroyobject  // destroy an object
    eventobject    // change the current event object
    function?      // test for the existence of a function
    getcurrobj     // get the current (executing) object
    geteventobj    // get the current event object
    getobjsize     // get number of variables & functions in an object
    inheritkeys    // enable/disable key inheritance
    object?        // test for the existence of an object
    objtype?       // test object inheritance hierarchy
    saveobject     // save an object to a file
    unsetx         // destroy an object variable


  The Define Statement
  ────────────────────
  The 'define' statement can improve the readability of your macros and
  make them easier to maintain by allowing you to define constants and
  compile-time functions. The format of the 'define' statement is:

    define
      .
      <macro statements>
      .
    end

  The 'define' statement evaluates all macro statements between the
  'define' and 'end' keywords at compile-time. Any object variables or
  functions defined within the scope of the 'define' statement have a
  lifetime limited to the macro language compilation process. No object
  code is generated for any source code contained within the 'define'
  statement.

  Object variables created within the 'define' statement can be
  referenced as constants outside the scope of the define statement.
  Similarly, functions defined within the 'define' statement will
  generate constant values when called outside the 'define' statement.
  For example:

    define
      _blue = 1
      _green = 2
      _cyan = 3

      // color calculation macro
      function  color (foreground on background)
        return  background * 16 + foreground
      end
    end

    say _green                // displays '1' (equivalent to 'say 2')
    say color green on blue   // displays '18' (equivalent to 'say 18')
    say color blue  on green  // displays '33' (equivalent to 'say 33')

  Note that the 'object' statement is not permitted within the scope of
  the 'define' statement. All source code contained within the 'define'
  statement is compiled and executed in a unique temporary object
  generated by the compiler. Since there is there is only one such
  object for all define statements, object variables and functions
  created in earlier 'define' statements are accessible from within the
  'define' statements which follow.


  The Include Statement
  ─────────────────────
  When writing macro source code, it is often convenient to place a
  section of code or definitions which are common to several files in a
  separate source file. The file can then be shared or 'included' by
  other source files. This technique avoids excessive duplication of
  source code and can also make the code easier to change.

  To include an external macro source file at the current location in
  your source code, use the 'include' statement. The format of the
  'include' statement is:

    include  expression

  where 'expression' is always evaluated at compile-time, using
  compile-time functions and variables created with the 'define'
  statement, if specified. For example:

    // simple example: includes the file 'c:\common.aml'
    include "c:\\common.aml"

    // define compile-time variables and functions
    define
      set include_path "c:\\aurora\\macro\\"
      function includefile (file)
        return include_path + file
      end
    end

    // complex example: includes the file 'c:\aurora\macro\common.aml'
    include includefile "common.aml"

  The 'include' statement can also be used to include compiled macro
  (.X) files:

    include "macro.x"

  This allows macro function libraries to be created and included in
  your source code, without the need to re-compile the library code. It
  also allows library '.X' files to be distributed without revealing the
  source code.


  Events
  ──────
  An important aspect of the macro language is the way in which events
  are handled. An event can be something that happens in the external
  world, such as a keypress or a mouse click, or something that happens
  internally to the editor, such as a timer event or a user-defined
  event. A macro language function can be defined by the user which is
  executed in response to the event. In this sense, the macro language
  is said to be 'event-driven'.

  When an event occurs, it is immediately placed in an internal area
  referred to as 'the event queue'. The next time the editor is not busy
  executing any macros, the event is read from the event queue and
  translated into a function name, with arguments if applicable. If a
  function with the same name has been properly defined by the user, the
  user function will be called automatically by the editor. This
  user-defined function is called the 'event handling' function. The
  entire process is referred to as 'dispatching an event'.

  The complete runtime operation of the editor can be briefly summarized
  by the following pseudo-code loop:

    loop forever
      if an event is in the queue then
        read the event from the queue
        translate the event into a function name
        call the event-handling function
      end
    end

  Many keyboard and mouse events have pre-defined event names enclosed
  in angled brackets, such as <ctrl x> or <lbutton>. These names should
  be used as the function name in event handling function definitions.
  For example:

    // <lbutton> is the event name for a left mouse button click
    function <lbutton>
      say "you pressed the left mouse button"
    end

  For better readability, keyboard event handling functions may be also
  defined with the 'key' statement, rather than the 'function' statement
  For example:

    key <ctrl x>
      say "you pressed <ctrl x>"
    end

  If the 'key' statement is followed by another 'key' or 'function'
  statement, the 'end' keyword is not required. For example:

    key <ctrl x>  say "you pressed <ctrl x>"
    key <ctrl y>  say "you pressed <ctrl y>"
    key <ctrl z>
      .
      .
    end


  The Current Event Object
  ────────────────────────
  The 'current event object' is where the editor dispatches events.
  Since no macros are usually executing when the editor dispatches an
  event, there is no 'current' object. Consequently, the editor always
  looks for the function in an object previously designated as the
  'current event object'.

  Only one object can be designated as the current event object at any
  given time. When the editor is initially started from the DOS command,
  the default object 'a' becomes the current event object.

  It is often useful to change the entire behavior of the keyboard and
  mouse simply by making another object the current event object. For
  example, when switching from a file manager window to an edit window,
  the editor simply changes the current event object, and a whole
  different set of keyboard and mouse event handling functions are
  enabled.

  Consider the following example:

    object edit
      key <ctrl x>  say "edit window"  end

    object fmgr
      key <ctrl x>  say "file manager window"  end

  In the example above, pressing <ctrl x> displays "edit window" when
  the current event object is the 'edit' object, and "file manager
  window" when the current event object is the 'fmgr' object.

  The current event object can be changed by using the builtin function
  'eventobject'. For example:

    eventobject "edit"   // designates 'edit' as the new event object

  The 'geteventobj' builtin function can be used to determine which
  object is the current event object:

    say (geteventobj)    // display the current event object

  Note: if a window has been associated with an event object via the
  'setwinobj' function, the current event object is automatically
  changed to the window event object when the window becomes the current
  window (see 'Windows').

  When an event is dispatched, and the event handling function is not
  found in the current event object, the editor will search the
  inheritance hierarchy of the current event object, in the same way as
  the hierarchy would be searched for a function call or object variable
  reference. In this way, an object inherits the event-handling
  capabilities of its parent objects.

  The 'pass' function can very useful when intercepting an event for
  pre-processing or post-processing. In effect, it 'passes on' the event
  or function call to the parent object(s) of the current object. For
  example:

  // mouse left button click
  function <lbutton>
    .
    <pre-processing>     // pre-process the event
    .
    pass                 // call <lbutton> in the parent object(s) of
    .                    //   of the current object
    .
    <post-processing>    // post-process the event
    .
  end


  User Defined Events
  ───────────────────
  User-defined events can be placed in the event queue from within an
  executing macro by using the 'queue' and 'queueobject' builtin
  functions. Once in the event queue, user-defined events are read and
  dispatched just like keyboard and mouse events.

  The 'queue' function places a function call (function + arguments) on
  the event queue. This effectively defers the execution of the function
  call until the next time the editor is idle. For example:

    queue "beep" 400 300

  In the example above, the function call "beep 400 300" is placed on
  the event queue. The next time the editor is idle, it will read "beep
  400 300" from the event queue and evaluate it in the current event
  object, just as if it were a keyboard or mouse event.

  The 'queue' function can also be used to simulate an external event
  such as a key press or a mouse click, without having the external
  event actually occur. The event handling function will be executed as
  if the event actually occurred. For example:

    queue <ctrl x>    // simulates pressing the <ctrl x> key
    queue <lbutton>   // simulates a left mouse button click

  User-defined events can also be directed to an explicitly specified
  object (instead of the current event object), by using the
  'queueobject' function. For example:

    queueobject "edit" "beep" 400 300

  In the example above, the function call "beep 400 300" is placed on
  the event queue. However, when the editor later reads the event, it
  will evaluate "beep 400 300" in the object "edit", not in the current
  event object.

  To generate an event and dispatch it immediately (synchronously,
  without using the event queue), the builtin functions 'send' and
  'sendobject' should be used. For example:

    send "beep" 400 300
    sendobject "edit" "beep" 700 200

  In the examples above, "beep 400 300" is evaluated immediately in the
  current event object, and "beep 700 200" is evaluated immediately in
  the object "edit".

  The 'call' function is similar to the 'send' function, except that the
  event is dispatched in the current (executing) object, not in the
  current event object.

  The following is a complete list of the event functions:

    call           // dispatch an event in the current object
    dispatch       // wait for and dispatch the next event
    endprocess     // return from a recursive invocation of the editor
    event?         // test if one or more events are in the event queue
    eventobject    // change the current event object
    getcurrobj     // get the current (executing) object
    geteventobj    // get the current event object
    pass           // call the current function in a parent object
    process        // invoke the editor recursively
    purgequeue     // remove all events from the event queue
    queue          // add an event to the event queue
    queueobject    // queue an event to a specific object
    send           // dispatch an event in the current event object
    sendobject     // dispatch an event to a specified object
    sizequeue      // change the event queue size


  Macro Types
  ───────────
  Since the editor is entirely written in its own macro language, there
  are many ways to organize your macro code. Nevertheless, most macros
  fall into three general categories:

  - Internal macros
  - External macros
  - Command Line macros


  Internal Macros
  ───────────────
  Internal macros are functions or collections of functions contained
  within the installed macro base of the editor, and are usually
  executed in response to an event such as keypress or a mouse click.
  These macros effectively become an integrated part of the editor and
  are automatically loaded when the editor is started. When the entire
  editor is compiled with the 'recompile' function (defined in EXT.AML),
  these macros will become embedded in A.X.

  Internal macros are typically used to perform common editing tasks
  unsuitable for 'external' macros. Examples of internal macros include:
  the keyboard and mouse event handling functions in KBD.AML and
  MOUSE.AML, the editor extension functions contained in EXT.AML, and
  the library functions in LIB.X.


  External Macros
  ───────────────
  In addition to internal macros, the editor also provides builtin
  functions for compiling and executing 'external' macros which reside
  in separate files. External macros can be individually loaded and
  executed after the editor is started and are typically used to perform
  less common editing tasks which do not require them to remain resident
  in the editor. The macros placed in the MACRO subdirectory at
  installation are examples of external macros.

  To compile an external macro source file and generate an executable
  macro file, use the 'compilemacro' function:

    compilemacro "macro.aml" "macro.x"

  The 'geterror' function can be used to retrieve compilation errors:

    geterror       // get the compilation error (0 = success)
    geterror 'k'   // get the column where error occurred
    geterror 'l'   // get the line where error occurred

  To run an executable macro file, use the 'runmacro' or 'includemacro'
  functions. For examples:

    runmacro "macro.x"      // load, execute, and discard 'macro.x'
    includemacro "macro.x"  // load and execute 'macro.x'

  'runmacro' loads the macro file and executes it in a temporary object
  which is descended from the current event object. When the macro is
  finished executing, the temporary object is destroyed and the macro is
  discarded.

  'includemacro' loads the macro file and executes it in the current
  event object. The macro file remains resident in the editor and any
  functions or object variables defined in the macro also remain
  resident. In effect, the 'includemacro' function converts an external
  macro into an internal macro.

  Note that macros executed by 'runmacro' and 'includemacro' do not
  require any special function 'entry points'. The code in an external
  macro is executed from top to bottom, just as the code within a
  function would be executed.


  Command Line Macros
  ───────────────────
  Command line macros are compiled external macros which are executed
  only once when the editor is started. These macros can be specified
  with the -x option on the DOS command line, or simply named A.X (the
  default command-line macro). For example:

    C>a                           // executes 'a.x'
    C>a -xtest.x                  // executes 'test.x' (but not a.x)
    C>a -xa.x -xalpha.x -xbeta.x  // executes 'a.x' first, then
                                  //   'alpha.x', and then 'beta.x'

  Command line macros can be used to:

  - perform some type of optional initialization before or after A.X is
      executed
  - perform a quick command-line editing operation not requiring
      the entire editor environment in A.X
  - completely replace the default editor environment in A.X

  The Aurora Editor is itself a command line macro contained in the file
  A.X. A.X is executed by default when the editor is started from the
  DOS command line without specifying the -x command line option.

  External source macros can also be compiled by using the 'c' command
  line option. For example:

    C>a -ctest.aml -cabc.aml   // compiles 'test.aml' to 'test.x'
                               //   and 'abc.aml' to 'abc.x'


  Compilation and Execution Functions
  ───────────────────────────────────
  The following is a complete list of the macro compilation and
  execution functions:

    builtin functions:
      compilemacro    // compile a macro source file
      eval            // evaluate a string as macro source code
      geterror        // returns error information
      includemacro    // load and execute a compiled macro file
      runmacro        // load, execute, and discard a compiled macro

    extension functions:
      askcmacro       // prompt to compile a macro source file
      askeval         // prompt to evaluate a macro expression
      askimacro       // prompt to include a compiled macro file
      askrmacro       // prompt to run a compiled macro file
      compilemacro2   // compile a macro source file (with messages)
      includemacro2   // load and execute a compiled macro file
      recompile       // recompile the editor
      runmacro2       // load, execute, and discard a compiled macro
      saveconfig      // recompile and save current config variables


  String Functions
  ────────────────
  In addition to the string concatenation '+' and substring '[:]'
  operators, the macro language provides useful builtin functions for
  searching and manipulating strings. Several of these functions are
  discussed briefly here.

  To determine the size (in characters) of a string or expression, use
  the 'sizeof' function:

    a = "apples"
    b = "oranges"
    sizeof a               // returns 6
    sizeof a + b           // returns 13
    sizeof ''              // returns 0
    sizeof 1563            // returns 4
    sizeof 49 + 51         // returns 3

  The 'pos' function returns the position of one string within another
  string. Search options may also be specified. For example:

    pos 'p' "apples"       // searches for 'p' in 'apples', returns 2
    pos 'p' "apples" 'r'   // searches in reverse for 'p', returns 3
    pos 'ES' "apples" 'i'  // ignores case, returns 5

  The 'sub' function replaces all occurrences of a string within another
  string. Search options can be specified. For example:

    sub 'p' '112' "apples"      // returns 'a112112les'
    sub 'es' 'y' "apples"       // returns 'apply'
    sub 'PL' '' "apples" 'i'    // returns 'apes'

  The 'upcase' and 'locase' functions change the case of a string:

    x = locase "APPLES"    // x is "apples"
    x = upcase "Apples"    // x is "APPLES"

  To convert integers to binary strings, use the 'char', 'char2', and
  'char4' functions:

    char 97                // returns 'a'
    char2 6261h            // returns 'ab'
    char4 64636261h        // returns 'abcd'

  To convert 1, 2, or 4 character binary strings to integers, use the
  'bin2int' function:

    bin2int 'a'            // returns 97
    bin2int 'ab'           // returns 25185
    bin2int 'abcd'         // returns 1684234849

  The 'pad' function can be used to pad a string with another string:

    pad "oranges" 10       // returns "   oranges"
    pad "oranges" 10 'l'   // returns "oranges   "
    pad 123 7 'r' '.'      // returns "....123"


  The following is a complete list of all the string functions:

    bin2hex   // convert binary strings to hex strings
    bin2int   // convert a 1, 2, or 4-byte string to an integer
    char      // convert integers to 1-byte strings
    char2     // convert integers to 2-byte strings
    char4     // convert integers to 4-byte strings
    concat    // concatenate strings together
    copystr   // duplicate a string one or more times
    flipcase  // toggle the case of each character in a string
    hex2bin   // convert hex strings to binary strings
    icompare  // test strings for equality (ignoring case)
    joinstr   // combine strings into a 'multistring'
    locase    // convert a string to lower case
    pad       // left or right justify a string and pad the string
    pos       // search for a string within another string
    poschar   // search for a character class in string
    posnot    // search for ~character class in string
    sizeof    // return size of a string (in characters)
    splitstr  // split a 'multistring' into substrings
    sub       // replace a substring within another string
    thousands // convert a number to a thousands-separated string
    upcase    // convert a string to upper case


  Miscellaneous Functions
  ───────────────────────
  Several important miscellaneous functions are provided by the macro
  language and are mentioned briefly here.

  The 'beep' function sounds the PC speaker:

    beep 700 400        // beeps at 700Hz for 400 milliseconds
    beep 700            // beeps at 700Hz indefinitely
    beep                // turns the speaker off

  To temporarily suspend execution of the editor, use the 'delay'
  function:

    delay 1000          // delay for 1000 milliseconds (1 second)

  The 'halt' function terminates execution of the editor immediately and
  unconditionally:

    halt       // terminate the editor immediately and exit to DOS

  To convert a decimal or hexadecimal number to a string representing
  the number in a new base, use the 'base' function:

    x = base 141 16                 // returns '8D' (base 16)
    x = base 141 8                  // returns '215' (base 8)
    x = base 141 5                  // returns '1031' (base 5)
    x = base 141 2                  // returns '10001101' (base 2)

  The 'eval' function evaluates a string of macro source code. This
  allows macro code to be dynamically constructed and executed from
  within an executing macro. For example:

    eval "beep " + " 700 300"      // beeps the speaker
    a = 40
    x = eval '3 + ' + a [1]        // x is '7'

  Note that local and global variables defined outside of the scope of
  the eval string are not accessible from within the 'eval' function.

  The following is a complete list of all the miscellaneous functions:

    arg    // access function arguments
    base   // convert a number to a string representing a new base
    beep   // beep the PC speaker
    delay  // suspend execution of a macro
    eval   // evaluate a string as macro source code
    exec   // execute a DOS program
    halt   // exit to DOS immediately
    peek   // return a copy of a DOS memory area
    poke   // modify a DOS memory area
    rand   // generate a random number


  Buffers
  ───────
  Perhaps the most basic concept in the editor is a text 'buffer'. A
  buffer is a file as it exists within the editor. Buffers may contain
  text from a file on disk, new text entered from within the editor, or
  both. Buffers are also used for manipulating temporary internal files.

  The editor maintains an internal list of buffers called the 'buffer
  list', with the 'current' buffer as the first buffer in the list. Each
  buffer is identified by a unique 'bufferid'. Not specifying a bufferid
  (or specifying a null bufferid) for many of the builtin buffer
  functions usually indicates that the 'current' buffer should be used.

  There are many functions which can be used to manipulate buffers. The
  most important functions are discussed briefly here. Most of these
  functions can be specified with several arguments, but are shown here
  in their simplest forms. See the AML Function Reference (FUNCTION.DOX)
  for a complete listing of buffer functions and their arguments.

  Buffers can be created by using functions like 'loadbuf' and
  'createbuf', saved with 'savebuf', and destroyed with 'destroybuf'.
  For example:

    if loadbuf "file.ext" then       // load a file into a buffer
      .
      <modify the text buffer>
      .
      savebuf "file.ext"             // save the buffer to a file
      destroybuf                     // destroy the buffer
    end

  The 'databuf' statement can be used to define a buffer within a macro,
  without requiring a separate file:

    databuf "abc"                    // define buffer 'abc'
      "first line"                   // 1st line
      x + y                          // 2nd line
      "last line"                    // 3rd line
    end

  Although these functions and statements are preferred for low-level
  manipulation of files within the editor, they do not associate a
  buffer with a window for interactive, event-driven editing. Library
  functions such as 'open' should be used to create or load buffers and
  display them for on-screen editing. For example:

    open "file.ext"   // load 'file.ext' into a new edit window

  Likewise, other library functions such as 'save' and 'close' should be
  used to save and destroy these buffers:

    save     // save the buffer in the current edit window
    close    // close the current edit window

  See 'Primary Editing Functions' for a complete listing of these
  higher-level functions.

  To retrieve a character from a buffer, use the 'getchar' function:

    // is the character at the cursor a blank?
    if getchar == ' ' then
      .
    end

  To retrieve a line or a portion of a line from a buffer, use the
  'gettext' function:

    // display the line at the cursor
    say "The line at the cursor is: " + gettext

  The 'getlinelen' and 'getlines' functions can be used to return the
  length of a line, and the number of lines in a buffer. For example:

    // is the cursor on a blank line?
    if not getlinelen then
      .
      .
    end

    // test if the number of lines in the current buffer
    // is greater than 5000
    if getlines >= 5000 then
      say "This is a large file!"
    end

  To enter text strings in a line, use the 'instext', 'ovltext', and
  'writetext' builtin functions, or the extension function 'write':

    instext "some text"    // insert 'some text' at the cursor
    ovltext "some text"    // overlay 'some text' at the cursor
    writetext "some text"  // insert or overlay 'some text' at the
                           //   cursor depending on the insert mode and
                           //   move the cursor to the end of the string
    write "some text"      // enter a string at the cursor, with support
                           //   for window settings such as word wrap,
                           //   translate, and match character

  The function 'delchar' will delete text in a line:

    delchar                // deletes the character at the cursor
    delchar 10             // deletes 10 characters at the cursor

  To insert new lines into a buffer or delete lines from a buffer, use
  the 'insline', 'insabove', and 'delline' functions:

    insline                // inserts a new blank line after the cursor
    insline "some text"    // inserts the new line "some text" after
                           //   the cursor
    insabove               // inserts a new blank line above the cursor
    delline                // deletes the line at the cursor

  The 'getcurrbuf' and 'getprevbuf' functions may be used to traverse
  existing buffers in the editor:

    buffer = getcurrbuf              // get the 'current' buffer
    while buffer do
      .
      .
      buffer = getprevbuf buffer     // get the previous buffer
    end

  The function 'hidebuf' will hide a buffer from the 'getprevbuf'
  function, so that it can not be traversed:

    hidebuf    // hide the current buffer

  'hidebuf' will also prevent buffers from being displayed on file lists
  generated by the editor library (LIB.X).

  The 'setbufname' function associates a descriptive name with a buffer,
  and the 'getbufname' function retrieves this name. For buffers created
  and manipulated with library functions (such as 'open') this name
  should always be a fully qualified file name:

    setbufname "C:\\FILE.EXT"  // change the name of the current buffer
    say (getbufname)           // display the name of the current buffer


  The following is a complete list of all the buffer functions:

    statements
      databuf       // define or add to a data buffer

    builtin functions:
      actualrow     // get the actual row over an apparent distance
      addline       // add a line to the end of a buffer
      apparentrow   // get the apparent row over an actual distance
      asciibuf      // create a buffer of ASCII characters
      bufchanged?   // test if buffer is modified
      buffer?       // test if a buffer exists
      bufferflag    // change buffer flags
      bufferflag?   // get buffer flags
      createbbuf    // create a new binary buffer
      createbuf     // create a new buffer
      currbuf       // change the current buffer
      delchar       // delete text on a line
      delline       // delete a line
      destroybuf    // destroy a buffer
      findbuf       // find a buffer with a given buffer name
      getbinarylen  // get binary line length used to load a buffer
      getbufname    // get the buffer name
      getchar       // get a character from a buffer
      getcurrbuf    // get the current bufferid
      getlinebeg    // get the starting column of a line
      getlinelen    // get the length of a line
      getlines      // get the total number of lines in buffer
      getloadinfo   // get directory information after loadbuf/insertbuf
      getprevbuf    // get the previous bufferid
      gettext       // get a line or a portion of a line from a buffer
      gotobuf       // change the default buffer for builtin functions
      hidebuf       // hide a buffer
      insabove      // insert a line before another line
      insertbuf     // insert a file into a buffer
      insline       // insert a line after another line
      instext       // insert a string into a line
      joinline      // join two lines into one line
      lineflag      // change line flags
      lineflag?     // get line flags
      loadbuf       // create a new buffer from a file or directory
      ovltext       // overlay a string onto a line
      printbuf      // print a buffer
      savebuf       // save a buffer to a file
      setbufname    // set the name associated with a buffer
      splitline     // split a line into two lines
      trunc?        // test if buffer was truncated when loaded
      undosize      // set the undo stack size for a buffer
      writetext     // insert or overlay a string in a line

    extension functions:
      backsp        // delete char to the left (with joinline)
      caseword      // change the case of the word at the cursor
      centerline    // center the line at the cursor
      commentline   // comment the line at the cursor
      delchar2      // delete the char at the cursor (with joinline)
      delword       // delete right word at the cursor
      enter         // enter key
      getword       // get the word at the cursor or at a column
      insline2      // insert a line with autoindent
      literal       // prompt to enter the next character literally
      livewrap      // live word wrap support
      splitline2    // split a line with autoindent
      swapline      // swap lines at the cursor
      tabfile       // detab or entab the current file
      timestamp     // enter the date and time at the cursor
      write         // enter a string at the cursor


  Cursors
  ───────
  A cursor identifies a movable column and row position in a buffer and
  usually marks the default location where text is entered. Cursors are
  normally visible in the window which displays the buffer.

  A cursor is always associated with only one buffer and may be created
  only after the buffer is created. All cursors associated with a buffer
  are automatically destroyed when the buffer is destroyed.

  For each buffer, the editor maintains an internal list of cursors
  called the 'cursor list', with the 'current' cursor as the first
  cursor in the list. Each cursor is identified by a unique 'cursorid'.
  Not specifying a cursorid (or specifying a null cursorid) for many of
  the builtin cursor functions usually indicates that the 'current'
  cursor should be used. Although it is possible to associate many
  cursors with a buffer, most buffers have only one cursor.

  There are many functions which can be used to manipulate cursors. The
  most important functions are discussed briefly here.

  The easiest way to create a cursor is to simply use a cursor function.
  If no cursor is associated with the current buffer, a cursor is
  automatically created before the function is executed. For example:

    if createbuf then    // create a new buffer
      right              // create a cursor and move it to the right
      .                  //   by 1 column
    end

  New cursors can also be created and destroyed with the 'setcursor' and
  'destroycursor' builtin functions (see the AML Function Reference).


  Note: the following cursor functions all operate on the 'current'
  cursor. No cursorid is specified.

  To retrieve the column and row position of the cursor, use the
  'getcol' and 'getrow' functions:

    // display the cursor position
    say "You're at column: " + getcol + ", row: " + getrow

  The 'insert?' function can be used to test whether or not the cursor
  is in insert or overstrike mode:

    // display the insert mode
    say "Insert mode " + ( if? insert? "ON" "OFF" )

  To move the cursor to a specific column and/or row, use the 'col',
  'row', and 'gotopos' functions:

    col 5           // move the cursor to column 5
    row (getlines)  // move the cursor to the last line in the buffer
    gotopos 14 671  // move the cursor to column 14, line 671

  The 'left', 'right', 'up', and 'down' functions can be used to move
  the cursor a relative distance away from the current cursor position:

    left     // move the cursor left 1 column
    right 3  // move the cursor right 3 columns
    up       // move the cursor up 1 line
    down 6   // move the cursor down 6 lines

  Since these functions return TRUE if the cursor is moved and FALSE if
  cursor cannot be moved, they can be used in conditional statements.
  For example:

    row 1
    repeat
      .
      <do something for every line in the buffer>
      .
    until not down

  To save and restore the current cursor position on an internal stack
  associated with the current buffer, use the 'pushcursor' and
  'popcursor' functions. For example:

    pushcursor    // save the cursor position
    row 1
    repeat
      .
      <do something for every line in the buffer>
      .
    until not down
    popcursor     // restore the cursor position


  The following is a complete list of all the cursor functions:

    builtin functions:
      col            // move the cursor to a column
      colorcursor    // change the cursor color
      currcursor     // change the current cursor
      cursor?        // test if a cursor exists
      destroycursor  // destroy a cursor and any associated window
      down           // move the cursor down
      getcol         // get the cursor column
      getcurrcurs    // get the current cursor
      getcurswin     // get window associated with a cursor
      getprevcurs    // get the previous cursor
      getrow         // get the cursor row
      gotopos        // move the cursor (absolute)
      insert?        // get cursor insert/overstrike mode
      lastpos        // move the cursor to the last cursor position
      left           // move the cursor left
      movepos        // move the cursor (relative)
      popcursor      // restore the cursor position from the cursor stack
      pushcursor     // save the cursor position on the cursor stack
      right          // move the cursor right
      row            // move the cursor to a row
      setcursor      // create a new cursor or change the cursor state
      up             // move the cursor up

    extension functions:
      enter        // the enter key
      nextword     // find the next word
      prevword     // find the previous word
      tableft      // tab left
      tabright     // tab right


  Bookmarks
  ─────────
  A bookmark identifies a stationary column and row position in a
  buffer. Bookmarks are often used to mark a position in the buffer to
  which the cursor will later be returned. Bookmarks are not visible in
  the window which displays the buffer.

  Like cursors, a bookmark is always associated with a specific buffer
  and may be created only after the buffer is created. All bookmarks
  associated with a buffer are automatically destroyed when the buffer
  is destroyed.

  For each buffer, the editor maintains an internal list of bookmarks
  called the 'bookmark list', with the 'current' bookmark as the first
  bookmark in the list. Each bookmark is identified by a unique
  'bookmarkid' (the name of the bookmark). Not specifying a bookmarkid
  (or specifying a null bookmarkid) for many of the builtin bookmark
  functions usually indicates that the 'current' bookmark should be
  used.

  To set a bookmark at the current cursor position, use the 'setbook'
  function. If the bookmark already exists, it is moved to the new
  position, otherwise a new bookmark is created. For example:

    setbook 'A'             // set bookmark 'A' at the cursor
    setbook "bookmark #1"   // set bookmark 'bookmark #1' at the cursor

  The 'destroybook' function will remove the bookmark:

    destroybook 'A'         // remove bookmark 'A'

  To move the cursor to a specific bookmark, use the 'gotobook'
  function:

    gotobook 'A'            // moves the cursor to bookmark 'A'


  The following is a complete list of the bookmark functions:

    builtin functions:
      currbook     // change the current bookmark
      destroybook  // destroy a bookmark
      getbookbuf   // get the buffer associated with a bookmark
      getcurrbook  // get the current bookmark for a buffer
      getprevbook  // get the previous bookmark in the buffer
      gotobook     // move the cursor to a bookmark
      setbook      // create a new bookmark or move an existing bookmark

    extension functions:
      askbook      // prompt for a bookmark to move to
      cyclebook    // cycle though all existing bookmarks
      gotobook2    // move cursor to a bookmark (with messages)
      placebook    // set a bookmark (with messages)
      quickbook    // place a 'quick' bookmark


  Marks
  ─────
  A mark defines an area of text in a buffer. Marks are usually visible
  in the window which displays the buffer. Once an area of text is
  marked, 'block' functions may be used to manipulate the text within
  the mark.

  A mark is always associated with a specific buffer and may be created
  only after the buffer is created. All marks associated with a buffer
  are automatically destroyed when the buffer is destroyed.

  For each buffer, the editor maintains an internal list of marks called
  the 'mark list', with the 'current' mark as the first mark in the
  list. Each mark is identified by a unique 'markid'. Not specifying a
  markid (or specifying a null markid) for many of the builtin mark
  functions usually indicates that the default markid '*' should be used
  (but not necessarily the current mark).

  Although it is possible to associate many marks with a buffer, most
  buffers have only one mark (with the default markid '*'), or no marks
  at any given time.

  There are many builtin functions which can be used to manipulate
  marks. The most important functions are discussed briefly here. Most
  of these functions can be specified with several arguments, but are
  shown here in their simplest forms. See the AML Function Reference for
  a complete listing of buffer functions and their arguments.

  Marks can be created with the 'markline', 'markcolumn', 'markchar',
  and 'markstream' functions, and destroyed with the 'destroymark'
  function. The type of mark created depends on which function is used.
  For example:

    markline                     // mark the line at the cursor and
                                 //   begin marking a series of lines
    markline 1 (getlines)        // mark the entire buffer
    markcolumn                   // begin marking a series of columns
    markcolumn 3 3 1 (getlines)  // mark the third column in the entire
                                 //   buffer
    markchar                     // mark the character at the cursor and
                                 //   begin marking a stream of chars
    markstream                   // begin marking a stream of characters
    destroymark                  // destroy the mark

  When any of the above functions are specified without arguments, the
  mark can be extended by moving the cursor until the function is called
  a second time. For example:

    row 1               // move the cursor to line 1
    markline            // mark the first line
    row 5               // extend the mark to line 5
    row (getlines)      // extend the mark to the whole buffer
    markline            // stop the cursor extension of the mark

  The 'mark?' function tests for the existence of a mark:

    if mark? then
       .
      <do if the mark '*' exists>
       .
    end

  The 'inmark?' function tests if the current cursor lies within a mark:

    key <del>           // the <del> key is pressed
      if inmark? then   // if the cursor is within a mark..
        deleteblock     // then delete the text in the mark
      else              // otherwise..
        delchar         // delete the character at the cursor
      end
    end

  The 'copymark' function makes a copy of an existing mark:

    copymark '*' 'T'    // now there are two marks: the orginal
                        // mark '*', and the new mark 'T'

  When the editor is started, the default markid is '*'. It is often
  useful to change the default markid when working with temporary marks
  to avoid altering marks created by the user (with the markid '*'). The
  'usemark' function is provided for this purpose:

    usemark 'T'         // change the default markid to 'T'
    markline            // create a temporary line mark
    shiftblock 1        // shift the marked text right one column
    destroymark         // destroy the temporary mark
    usemark             // always change the default markid back to '*'


  The following is a complete listing of all the mark functions:

    builtin functions:
      colormark      // change the mark color
      copymark       // mark a copy of a mark
      currmark       // change the current (top) mark
      destroymark    // destroy a mark
      extendmark     // extend the current mark to the cursor position
      getcurrmark    // get the current mark for a buffer
      getmarkbot     // get the bottom row of a mark
      getmarkbuf     // get the buffer associated with the mark
      getmarkcols    // get the mark width
      getmarkleft    // get the left column of mark
      getmarkright   // get the right column of mark
      getmarkrows    // get the mark height
      getmarktop     // get top row of a mark
      getmarktype    // get the mark type
      getmarkuse     // get the default markid
      getprevmark    // get the previous mark
      inmark?        // test if a cursor position is inside a mark
      mark?          // test for the existence of a mark
      markchar       // begin or extend a char mark
      markcolumn     // begin or extend a column mark
      markline       // begin or extend a line mark
      markstream     // being or extend a stream mark
      stopmark       // stop the cursor extension of a mark
      usemark        // change the default markid

    extension functions:
      getmarktext    // get top line of text in a mark
      markeol        // mark to the end of the current line
      markpara       // mark the paragraph at the cursor
      markword       // mark the word at the cursor
      smark          // allow CUA <shift> marking after cursor movement


  The following is a complete listing of all the 'block' functions which
  can be used to manipulate a marked block of text:

    builtin functions:
      caseblock      // change the case of text in a mark
      copyblock      // copy the text in a mark
      copyblockover  // overlay the text in a mark over other text
      deleteblock    // delete the text in a mark
      tabblock       // expand the tab characters (ASCII 9) in a mark
      fillblock      // fill a mark with a repeating character or string
      foldblock      // manipulate folds in a mark
      formatblock    // reformat the text in a mark
      justblock      // justify the text in a mark
      moveblock      // move the text in a mark
      printblock     // print the text in a mark
      saveblock      // save the text in a mark
      shiftblock     // shift the text in a mark left or right
      sortblock      // sort the text in a mark

    extension functions:
      copyblock2     // copy a block (or a line) of text
      deleteblock2   // delete a block of text
      fillblock2     // prompt to fill a mark with a string
      formatblock2   // reformat a block or paragraph
      justblock2     // justify a block of text between margins
      moveblock2     // move a block of text
      moveblockover  // move a block of text over other text
      quote          // quote a paragraph or a block of text
      saveblock2     // save a block of text
      sortblock2     // sort a block of text

    Clipboard support is implemented in the following extension
    functions by using the 'mark' and 'block' functions:

      askclip        // prompt to change the current clipboard
      clear          // erase the contents of a clipboard
      copy           // copy or copy-append to a clipboard
      cut            // cut or cut-append to a clipboard
      paste          // paste or paste-over from a clipboard


  Undo and Redo
  ─────────────
  The ability to 'undo' and 'redo' certain editor functions is an
  advanced feature of the macro language. This feature allows you to
  backtrack and retrace the changes made to a buffer. The types of
  'undoable' functions include:

    - functions which modify buffers
    - functions which create or modify marks
    - functions which create or modify folds
    - functions which move the cursor (under special circumstances)

  In general, all text changes, folding, and marking can be undone.
  Cursor movements are also undone, but only when associated with text
  changes, folding, and marking, or explicitly specified with the
  'undocursor' function.

  To allow buffer changes to be undoable, an undo/redo stack must be
  created for the buffer by using the 'undosize' function. For example:

    undosize 500    // allow a maximum of 500 changes to be undone

  The 'undo' function can then be used to undo changes to the buffer,
  one at a time:

    undo    // undo one change

  Changes which were undone with 'undo' can be reinstated with the
  'redo' function:

    redo    // redo one change

  Multiple changes to a buffer can be grouped together as one undoable
  operation by using the 'undobegin' and 'undoend' functions. For
  example:

    undobegin            // beginning of an undoable group
    delline              // 1st change to the buffer
    instext "a string"   // 2nd change to the buffer
    insline              // 3rd change to the buffer
    undoend              // end of an undoable group
     .
     .
    undo                 // all 3 changes are undone as one operation

  Undoable groups can be nested. In this case, the outermost
  undobegin-undoend pair denotes the undoable group. The inner
  undobegin-undoend pairs are ignored.

  The 'undocursor' function can also be used to save the current cursor
  position as an undoable operation on the undo/redo stack.

  The following is a complete list of the undo and redo functions:

    redo         // redo the last change or group of changes
    undo         // undo the last change or group of changes
    undobegin    // start a group of undoable operations
    undocursor   // save the cursor position on the undo/redo stack
    undoend      // end a group of undoable operations
    undosize     // associate an undo/redo stack with a buffer


  Search and Replace
  ──────────────────
  The editor provides many functions for searching through files and
  replacing strings, and for scanning multiple files for a string.

  The builtin functions 'find' and 'replace' will search for, and
  replace strings in a buffer. Many different search options can be
  specified in various combinations, and searches can be confined to a
  mark. For example:

    find "apples" "*ir"
      // searches for 'apples' (case insensitive) starting at the cursor
      //   and searching toward the beginning of the buffer

    replace "apples" "oranges" "ag"
      // replaces all occurrences of "apples" with "oranges" in the
      //   current buffer

  See the AML Function Reference for a complete description of the
  'find' and 'replace' functions, and search options.

  The higher-level library function 'search' can also be used for both
  searching and replacing. Unlike the 'find' and 'replace' functions,
  arguments to the 'search' function are specified as one combined
  'multistring'. For example:

    search "apples/ir*"
    search "apples/oranges/ag"

  See the AML Function Reference for complete description of the
  'joinstr', 'splitstr' functions, and multistrings.

  The functions 'scanfile' and 'searchfiles' will both scan multiple
  files for a string and create a new file manager window showing all
  files where the string was found. Whereas separate arguments are
  specified for 'scanfile', arguments to 'searchfiles' are specified as
  one combined 'multistring'. For example:

    scanfiles "C:\\*.TXT"  "apples"  "iw"  // separate search arguments

    searchfiles "apples/C:\\*.TXT/iw"      // 'multistring' arguments


  The following is a complete list of the search and replace functions:

    builtin functions:
      find         // search for a string
      replace      // search for a string, replace with another string

    library functions:
      gotoerror    // go to the compiler error on the current line
      gotomatch    // find the matching character
      scanfiles    // scan files for a string
      search       // search or replace within the current file

    extension functions:
      askcol       // prompt for a column to go to
      askfind      // prompt for a search (multistring)
      askfindo     // prompt for find occurrences of a string
      askrepl      // prompt for search and replace (multistring)
      askrow       // prompt for a row to go to
      askscan      // prompt to scan files for a string
      col2         // go to a column (absolute or relative +/-)
      findlast     // repeat the last search/replace
      findlasto    // find occurrences of the last search string
      findo        // find occurrences of a string
      gotomark     // go to an edge of a mark
      gotomatch2   // find the matching char (with highlight)
      isearch      // incremental search
      row2         // go to a row (absolute or relative +/-)
      search2      // search/replace with messages and highlighting
      searchfiles  // scan files for a string (multistring arguments)


  Folds
  ─────
  Folds are an advanced feature of the editor which allow you to escape
  the normal 'flat text' mode of editing. Using folds, you can impose a
  hierarchal structure on your text, giving it the appearance and
  behaviour of an electronic outline.

  Using folding functions, multiple lines of text in a buffer can be
  'folded together' and made to appear as one line in a window. Any
  number of folds of any size can be created. Folds can be nested by
  folding a group of lines which already contain other folds. Folds
  within a fold are referred to as 'subfolds'.

  Folds can also be opened for viewing or editing, and saved along with
  the text in a buffer. All folding operations are 'undoable' (see 'Undo
  and Redo').

  Folds may be also excluded from searching by the specifying the 's'
  (skip) search option. See the 'find' function in the AML Function
  Reference for description of search options.

  The following is a complete list of the folding functions:

    builtin functions:
      closefold      // close a fold (and optionally, subfolds)
      createfold     // create a one-line 'open' fold
      destroyfold    // destroy a fold (and optionally, subfolds)
      fold?          // test for the existence of a closed fold
      foldblock      // manipulate folds within a mark
      getfold        // get information about a fold
      openfold       // open a fold (and optionally, subfolds)

    extension functions:
      foldall        // manipulate all folds in a buffer
      foldline       // fold or unfold a line


  Timers
  ──────
  A 'timer' is a macro language facility that allows user-defined events
  to be generated automatically at timed intervals, or at a specific
  time and date.

  To set a timer to call a function only once after a specified time
  interval has elapsed, use the 'settimer' function. For example:

    settimer 'mytimer' 1500 '' 'beep' 700 300
      // sets the timer 'mytimer' to execute the function call 'beep 700
      //   300' in the current event object 1.5 seconds from now

  Note that:

    settimer 'mytimer' 0 '' 'beep' 700 300   // time interval is zero

      //..is equivalent to:

    queue 'beep' 700 300

  A timer specified with the 'settimer' function is automatically
  destroyed after one event is generated. To set a timer which repeats
  at regular intervals, use the 'setrepeat' function. For example:

    setrepeat 'mytimer' 1500 '' 'beep' 700 300
      // sets the timer 'mytimer' to execute the function call 'beep 700
      //   300' every 1.5 seconds in the current event object

  Specifying a zero time interval in the 'setrepeat' function will
  create a repeating timer which generates an event whenever the editor
  is idle. This can be used to create 'idle-time' macros:

    setrepeat 'mytimer' 0 '' 'myfunction'
      // sets the timer 'mytimer' to call 'myfunction' in the
      //   current event object whenever the editor is idle

  A timer specified with the 'setrepeat' function will continue to
  'fire' until it is destroyed with the 'destroytimer' function:

    destroytimer 'mytimer'   // destroys the timer 'mytimer'

  To create a timer which generates an event at a specific date and
  time, use the 'setalarm' function:

    setalarm 'mytimer'  // set the alarm timer 'mytimer' to fire:
       1995             // in year 1995
       1                // on january
       12               // 12th,
       -1               // any day of the week
       22               // at 10 o'clock at night
        0               // zero minutes past 10
        0               // zero seconds past zero minutes
       ''               // dispatch in the current event object
       'beep' 700 300   // execute the function call 'beep 700 300'

  If -1 is specified for any of the 'setalarm' arguments, those arguments
  become 'wildcards' (the timer will fire for any values of those
  arguments). For example:

    // sets the timer 'mytimer' to beep once every hour on Tuesdays
    setalarm 'mytimer'
       -1               // any year
       -1               // any month
       -1               // any day
        2               // only on Tuesdays
       -1               // any hour
        0               // only at zero minutes past the hour
        0               // only at zero seconds past zero minutes
       ''               // dispatch in the current event object
       'beep' 700 300   // execute the function call 'beep 700 300'


  The following is a complete list of the builtin timer functions:

    destroytimer   // destroys a timer
    setalarm       // sets an alarm timer
    setrepeat      // sets a repeating interval timer
    settimer       // sets a non-repeating interval timer
    timer?         // tests for the existence of a timer


  Windows
  ───────
  A window is a rectangular area of the screen used to display buffers,
  simple video output, or other child windows.

  If a window displays a buffer, it must be associated with a specific
  cursor in the buffer. Since a buffer may contain many cursors,
  multiple windows may be used to display different areas of the same
  buffer.

  The editor maintains an internal list of windows called the 'window
  list', with the 'current' window as the first window in the list. Each
  window is identified by a unique 'windowid'. Not specifying a windowid
  (or specifying a null windowid) for many of the builtin window
  functions usually indicates that the 'current' window should be used.

  There are many builtin functions which can be used to manipulate
  windows. The most important functions are discussed briefly here. Many
  of these functions can be specified with several arguments, but are
  shown here in their simplest forms.

  To create and destroy windows, use the 'createwindow' and
  'destroywindow' functions:

    createwindow
      .
      <set the window appearance>
      .
      <display items in the window>
      .
    destroywindow

  Once a window has been created, there are several functions which can
  be used to change detailed aspects of the windows appearance.

  When a window is initially created, it is just a simple rectangle
  covering the entire screen. The 'setframe' function adds or removes
  window 'frame components'. Frame components are features in the window
  frame such as borders, title bars, and menu bars. For example:

    createwindow     // create a new window
    setframe 'bn'    // add borders and north title bar to the window

  Borders are initially created with a thickness of zero, so the
  'setborder' function should be used to set the border thickness and
  style:

    setborder '1'    // use border style '1' (default thickness = 1)

  Since a title bar was specified in the 'setframe' function call, you
  will probably want to set the window title using the 'settitle'
  function:

    settitle "Hello World!"

  You can also add window controls and a shadow with the 'setwinctrl'
  and 'setshadow' functions:

    setwinctrl '≡'   // add a 'close' icon
    setshadow 2 1    // set the shadow thickness

  You may wish also wish to change the window colors by using the
  'setcolor' function:

    setcolor  border1_color      color white on gray   // border color
    setcolor  text_color         color black on gray   // text color
    setcolor  north_title_color  color white on green  // title color

  Finally, you can change the size and/or position of the window
  using the 'sizewindow' function:

    sizewindow 6 5 72 20 'ad'   // size window relative to the screen

  Now that the window has been created and styled to your preferences,
  you will probably want to display something in the window 'client
  area'. The client area is the main area in the middle of the window
  which is not part of the borders, menus, or titles.

  If you are using the window for simple video output, the 'writestr'
  and 'writeline' functions can be used to display strings in the window
  client area, and the 'gotoxy' function can be used to change the
  position of the video cursor:

    writestr "A string"    // write a string
    gotoxy 5 2             // go to column 5, row 2 in the window

    writeline "A line and a carriage return"
      // write a string with a carriage return,
      //   scrolling the window if needed

  Note that this window does not display a buffer. The cursor is a
  simple video cursor, not the type of cursor associated with a buffer
  (see 'Cursors').

  Since the video cursor is still hidden at this point, you may wish to
  display it with the 'showcursor' function:

    showcursor 80 90   // display the cursor near the bottom of the
                       //   character cell

  As you are writing text to the client area, you can use the 'display'
  function to force the editor to update the display before continuing:

    writeline "a line"              // write some lines
    writeline "another line"
    display                         // update the display
    writeline "yet another line"

  To display a buffer in a window, the video window functions described
  above (writestr, writeline, gotoxy) are not sufficient. Buffers are
  displayed in a window by first creating a cursor for the buffer and
  then attaching the cursor to a window by using the 'setwincurs'
  function. For example:

    cursor = createcursor  // create a cursor for the current buffer
    setwincurs cursor      // attach the cursor to the current window

  Once this connection has been established, any changes made to the
  cursor or the buffer will be displayed automatically in the window the
  next time the editor becomes idle. The 'display' function can still be
  used to force the editor to update the display as changes are being
  made to the buffer or the cursor. For example:

    writetext "Some text"        // enter text in the buffer
    display                      // show the text
    writetext "Some more text"   // enter more text, but don't display
                                 //   it until the editor becomes idle

  Windows which display buffers can also be scrolled. The following is a
  complete list of the builtin scrolling functions:

    adjustcol    // adjust left window view offset
    adjustrow    // adjust top window view offset
    pagedown     // scroll down one page
    pageup       // scroll up one page
    rollcol      // scroll left or right by a relative amount
    rollrow      // scroll up or down by a relative amount
    scrollcol    // scroll directly to a column
    scrollrow    // scroll directly to a row

  A window can be associated with an event-handling object by using the
  'setwinobj' function:

    setwinobj "edit"
      // associate the current window with the 'edit' object

  When a window has been associated with an event-handling object, the
  current event object will be automatically set to that object whenever
  the window becomes the current window. In this way, an entire set of
  keyboard and mouse event handling functions are associated with a
  particular window or window type. The event-handling object becomes,
  in effect, the 'window class'.

  For example in the default editor setup, edit windows are associated
  with the 'edit' object and file manager windows are associated with
  the 'fmgr' object. When you switch between edit and file manager
  windows, the current event object is automatically changed, resulting
  in different keyboard and mouse behaviour for each window.

  The 'wintype?' builtin function can be used to test the entire
  inheritance hierarchy or 'object ancestry' associated with a window.
  For example:

    // test if the event-handling object associated with the
    //   the current window is descended from the 'edit' object
    //   (or put more simply, 'is this an edit window?')
    if wintype? 'edit' then
      .
      <do only for edit windows>
      .
    end


  The following is a complete list of the window functions:

    builtin functions:
      createwindow   // create a new window
      destroywindow  // destroy a window
      display        // update the display
      eotstring      // change the 'end-of-text' line in a window
      frame?         // test for window frame components
      getborder      // get window border information
      getbotwin      // get the windowid of the bottommost window
      getchild       // get a child windowid
      getcolor       // get window colors
      getcoord       // get window dimensions and coordinates
      getcurrwin     // get the windowid of the topmost window
      getnextwin     // get the windowid of the next window
      getparent      // get a parent windowid
      getprevwin     // get the windowid of the previous window
      getregion      // get a window region from virtual coordinates
      gettitle       // get a window title
      getviewbot     // get the bottommost visible row in window
      getviewcols    // get the visible window width
      getviewleft    // get the leftmost column in window
      getviewright   // get the rightmost visible column in window
      getviewrows    // get the visible window height
      getviewtop     // get the topmost row in a window
      getwinbuf      // get the bufferid associated with a window
      getwincount    // get the number of windows or child windows
      getwinctrl     // get a title bar control
      getwincurs     // get the cursorid attached to a window
      getwinobj      // get object name associated with a window
      getwinscr      // get a scroll bar position from virtual coords
      gotowindow     // change the default window for builtin functions
      hidecursor     // hide a cursor (temporarily for buffer windows)
      hidewindow     // hide a window temporarily
      hilite         // highlight text in a window
      movewindow     // move a window to a new location
      setborder      // change the window borders
      setcolor       // change the window colors
      setframe       // add or remove window frame components
      setnextwin     // set the next window
      setparent      // set the parent window
      setprevwin     // set the previous window
      setshadow      // set the window shadow
      setshadow2     // set the 1/2 window shadow
      settitle       // change a window title
      setwinctrl     // define window title bar controls
      setwincurs     // attach a cursor (and a buffer) to a window
      setwinobj      // associate a window with an object
      showcursor     // show a cursor
      showwindow     // show a hidden window
      sizewindow     // change the size of a window
      tilewindow     // tile windows
      virtocol       // convert a virtual X-coordinate to a column
      virtorow       // convert a virtual Y-coordinate to a row
      window?        // test for the existence of a window
      wintype?       // test the window event object hierarchy

      Note: the following builtin functions are only meaningful in video
      output windows (windows which do not display a buffer):

      clearwindow    // clear the contents of a video window
      getx           // get the column of video window cursor
      gety           // get the row of video window cursor
      gotoxy         // move the cursor of video window
      writeline      // display a string and CR in a video window
      writestr       // display a string in a video window

    library functions:
      cascade        // cascade all windows
      copywin        // copy the current edit window
      currwin        // change the current window
      deletewin      // delete the current window
      getsettings    // get the current window settings
      max?           // test if the current window is maximized
      maximize       // maximize the current window
      min?           // test if the current window is minimized
      minimize       // minimize the current window
      nextwindow     // switch to the next window
      pankey         // pan the video background with the keyboard
      prevwindow     // switch to a previous window
      restore        // restore the current window
      setdraw        // set the window line-drawing style
      setting        // change a window setting
      setting?       // test if specified window settings are ON
      sizekey        // resize or move the current window with the kbd
      sizewin        // resize or move the current window
      splitwin       // split the current edit window
      tile           // tile all windows horizontally or vertically
      togglestyle    // toggle the style of the current window
      toolbar        // display a toolbar on the current window
      winlist        // display a popup menu of open windows


  Video Functions
  ───────────────
  Several functions are provided which allow you to control certain
  characteristics of the video device or retrieve information about the
  current state of the video device.

  When viewing the editor, the display device is only a small window
  into the 'virtual' screen actually used by the editor. Although your
  screen may only display 80 columns by 25 rows at one time, the size of
  the virtual screen is actually 64000 x 64000 characters.

  When the editor is initially started, the physical display device is
  located at column 16000 and row 16000 of the virtual screen. You can
  adjust this mapping of the physical screen to the virtual screen by
  using the 'pan' and 'panto' builtin functions:

    pan 10 -2           // pan right 10 columns, up 2 rows
    panto 17000 17000   // pan to virtual screen location 17000,17000

  You can use the 'videomode' library function to change the video mode:

    videomode 80 50     // set the video mode to 80 x 50
    videomode 80 28     // set the video mode to 80 x 28

  To write text on the screen background, use the 'writebak' function:

    writebak "The date is: " + getdate  2 2 color black on gray
      // writes the date on the screen background at column 2 row 2
      //   relative to the upper left corner of the screen, using
      //   the color 'black on gray'

  The following is a complete list of the video functions:

    builtin functions:
      blink         // enable or disable the video blink mode
      getpalette    // return a color attribute or the entire palette
      getvidbot     // return the bottom edge of the virtual screen
      getvidcols    // return the screen width
      getvidleft    // return the left edge of the virtual screen
      getvidright   // return the right edge of the virtual screen
      getvidrows    // return the screen height
      getvidtop     // return the top edge of the virtual screen
      mono?         // test for a monochrome display
      pan           // pan the virtual screen (relative)
      panto         // pan the virtual screen (absolute)
      setdisplay    // enable/disable display updating
      setpalette    // define the color palette
      setvideo      // change video mode/background
      showentry     // show the entry screen when the editor was started
      videoborder   // change the video overscan border color

    library functions:
      videomode     // change the video mode

    extension functions:
      togglemode    // toggle the video mode between 80x25 and 80x50


  Syntax Highlighting
  ───────────────────
  Syntax Highlighting is an editor feature which automatically colors
  characters, words, and phrases in a buffer when the buffer is
  displayed in a window. This feature can be used to highlight the
  source code of many different programming languages, or even text
  files. Using a few simple functions and statements, you can easily
  configure how elements in your text are highlighted.

  To specify how you would like your text to be highlighted, a syntax
  highlighting object must first be defined. A syntax highlighting
  object is created with the 'object' statement, in the same way as
  other objects are created. The 'syntax' function is then called within
  the object to create a syntax highlighting 'template' for the object.
  The template specifies highlighting options, syntax elements to be
  highlighted, and highlighting colors. For example:

    // syntax highlighting object for AML
    object aml

      syntax

        // syntax highlighting options
        'bin'                           // b=show through marked block
                                        // c=don't highlight cursor line
                                        // i=ignore keyword case
                                        // n=highlight numbers

        // language elements to be highlighted
        '()=+-*/<>|&^,[]:'              // symbol set
        '"\''                           // string characters
        '\\'                            // string literal char
        ''                              // numeric char
        '//'          0                 // eol comment 1 / start column
        ''            0                 // eol comment 2 / start column
        '/*'          '*/'              // multi-line comment 1
        ''            ''                // multi-line comment 2
        0                               // number of lines to scan backward

        // colors
        color brightcyan   on blue      // keyword color
        color gray         on blue      // symbol color
        color brightred    on blue      // string color
        color brightred    on blue      // numeric color
        color brightgreen  on blue      // eol1 comment color
        color yellow       on blue      // eol2 comment color
        color brightgreen  on blue      // comment1 color
        color brightcyan   on blue      // comment2 color

  (see the 'syntax' function in the AML Function Reference for a
  description of syntax parameters).

  To define keywords to be highlighted, use the 'keyword' statement
  within the syntax highlighting object:

    object aml
        .
        .
      // define AML keywords to highlight
      keyword
        if, then, else, elseif, if?, case, when, otherwise, function,
        set, setobj, setx, setxobj, object, while, do, repeat, until,
        .
        .

  Keywords do not need to be entered in any specific order.

  Syntax highlighting keywords are actually stored as object variables
  in the syntax highlighting object. The value of the object is the
  keyword color, or zero if the color specified in the template is to be
  used. This allows you to dynamically assign different colors to
  individual keywords, or define new keywords on-the-fly. For example:

    // change the color of the keywords 'if' and 'then'
    // from the default template color
    _if    = color white on green
    _then  = color white on brightred

    // add a new keyword from within a macro
    _myvar = color white on magenta


  The 'setsyntax' statement associates or disassociates a syntax
  highlighting object with a window. For example:

    // attach the AML syntax highlighting object to the current window
    // and turn it ON.
    setsyntax ON "aml"


  The following is a complete listing of the syntax highlighting
  functions and statements:

    statements:
      keyword      // define syntax highlighting keywords

    builtin functions:
      setsyntax    // enable or disable syntax highlighting for a window
      syntax       // define a syntax highlighting template for the
                   //   current object

    extension functions:
      onsyntax     // called by the editor library (LIB.X) to get the
                   //   syntax highlighting object for a filename
      hiliteword   // dynamically define the word at the cursor as
                   //   a syntax highlighting keyword


  File Handling Functions
  ───────────────────────
  The macro language provides many useful functions for manipulating
  files on disk, and for retrieving path and drive information. A few of
  these functions are discussed briefly here.

  To convert a filename to a fully-qualified filename, use the 'qualify'
  function:

    qualify "file.txt"
      // returns C:\FILE.TXT if C:\ is the current path
    qualify "file.txt" "e:\\doc\\abc.doc"
      // returns E:\DOC\FILE.TXT

  The 'locatefile' function can be use to search a directory or path for
  a file:

    locatefile "FILE.TXT" (getenv "PATH")
      // returns FILE.TXT (fully qualified), if FILE.TXT is
      //   found in the DOS PATH

  To retrieve different parts of a filename, use the 'getpath',
  'getname', and 'getext' functions:

    getpath "d:\\aurora\\kbd.aml"   // returns 'd:\aurora\'
    getname "d:\\aurora\\kbd.aml"   // returns 'kbd.aml'
    getext  "d:\\aurora\\kbd.aml"   // returns '.aml'


  The following is a complete list of the file handling functions:

    builtin functions:
      bootpath       // get a filename in terms of the editor bootpath
      chgfileattr    // change file attributes
      closefile      // close an open file
      copyfile       // copy a file
      createdir      // create a new directory
      currpath       // change the current drive and/or path
      deletefile     // delete a file
      fileattr?      // test file attributes
      filepos        // change the position in an open file
      getbootpath    // get the editor invocation path
      getcurrpath    // get the current DOS path
      getdisk        // get disk drive information
      locatefile     // search for a file or directory in a path
      openfile       // open a file and return a file handle
      qualify        // get a fully qualified filename
      readfile       // read from an open file
      renamefile     // rename a file
      scanfile       // scan a file for a string
      setbootpath    // change the bootpath
      touchfile      // update the date and time of a file
      writefile      // write to an open file

    library functions:
      dir?           // test if a filespec is a directory

    extension functions:
      defext         // append a default extension if no extension
      forceext       // force a filename to have an extension
      getext         // get the extension portion of a filespec
      getname        // get the name & extension portion of a filespec
      getpath        // get the drive & path portion of a filespec


  System Functions
  ────────────────
  The editor also provides builtin functions to control and retrieve
  information about the operating environment of the editor. These
  functions control memory usage and printer devices, and return
  information such as the date and time, environment strings, and
  version numbers.

  Some system functions are usually called only once for each edit
  session:

    cursorsize     // set the insert and overstrike cursor size
    international  // define international date and time formats
    maxems         // define the amount of EMS memory to use
    maxxms         // define the amount of XMS memory to use
    memoptions     // set memory usage options
    printformat    // define the initial printer settings
    speaker        // enable or disable the PC speaker
    swapfiles      // define the swapfiles to use

  Other system functions return information about the operating
  environment:

    getenv         // return the value of a DOS environment variable
    getexe         // return the editor .EXE file name
    getos          // return the operating system version
    getversion     // return the current version of the editor

    getrawtime     // return the time and date in raw format
    getdate        // return the date in international format
    gettime        // return the time in international format


  The Keyboard
  ────────────
  When a key is pressed on the keyboard, the editor will generally
  respond by calling a user defined event-handling function accessible
  from within the current event object. For example:

    // move the cursor to the top line when <ctrl x> is pressed
    key <ctrl x>
      row 1
    end

  The keycode is passed as the first argument:

    // display the keycode for <ctrl x>
    key <ctrl x> (keycode)
      say "The keycode for <ctrl x> is: " + keycode
    end

  The event-handling function names for most keyboard function keys
  (<ctrl x>, <shift f3>, etc.) are predefined within the editor (see
  'Appendix A: Key Event Names').

  When any shift key is pressed (<shift>, <ctrl>, <scroll lock>, etc.),
  the editor will call the '<shiftkey>' event-handling function, passing
  the old keyboard shift state and the new keyboard shift state.

  When a single character, non-function key such as 'a', or 'Z' is
  entered, the editor will call the '<char>' event-handling function,
  passing the character entered as the first argument and the keycode as
  the second argument. For example:

    // insert non-function keys into the buffer at the cursor
    key <char> (character keycode)
      writetext character
    end

  If the editor attempts to dispatch a keyboard event, but does not find
  an event-handling function for the event within the current event
  object (or within the object hierarchy), the editor will call the
  default function '<otherkey>', passing the keycode of the key entered.
  For example:

    // undefined keys
    key <otherkey> (keycode)
      say (getkeyname (keycode)) + " not defined"
    end

  The '<otherkey>' event-handling function can also be used to respond
  to special hardware-specific keycodes for which the editor has no
  predefined names.

  When any shift key (<shift>, <ctrl>, <scroll lock>, etc.) is pressed
  or released, the editor will call the '<shiftkey>' event-handling
  function, passing the old keyboard shift state and the new keyboard
  shift state. The old and new shift states can be compared by the
  event-handling function to determine what shift key event actually
  occurred (see the 'shiftkey?' function in the AML Function Reference
  for a description of the shift state). For example:

    key <shiftkey> (newstate oldstate)
      if newstate & 3 and not (oldstate & 3) then
        send "shiftdown"
      elseif oldstate & 3 and not (newstate & 3) then
        send "shiftup"
      end
    end


  By default, the inheritance hierarchy of an object is searched
  whenever a keyboard event-handling function is not found in the
  object. The 'inheritkeys' function can be used to enable or disable
  the inheritance of keyboard events in the object in which it is
  called. For example:

    object abc
      inheritkeys OFF  // turn off kbd inheritance in object 'abc'

  'inheritkeys' can be used by an object to temporarily block parent
  objects from handling any keyboard events.

  Whenever possible, user-defined event-handling functions (as shown
  above) should be used to respond to keyboard events. However, it is
  sometimes necessary to wait for a keypress from within a macro. The
  'getkey' function waits for the next key and returns the keycode for
  the key pressed. For example:

    keycode = getkey
    if keycode == <ctrl x> then
      row 1
    end

  If the mouse is clicked while getkey is waiting for a key, the keycode
  '<button>' is returned. Note that 'getkey' should be used only in
  situations where an event-handling function will not be sufficient,
  since it will prevent other events from being dispatched.

  The 'getkeyname' and 'getkeycode' functions can be used to get the
  event-handling function name associated with a keycode, and vice
  versa. For example:

    keycode = getkey               // wait for a key
    keyname = getkeyname keycode   // get the keyname for the keycode
    keycode = getkeycode keyname   // doesn't change 'keycode'

  The 'sendkey' and 'queuekey' functions can be used to execute the
  event-handling functions associated with keycodes:

    keycode = getkey   // wait for a key and get a keycode
    sendkey keycode    // dispatch the key immediately
    queuekey keycode   // queue the key

  To test the current shift-state of the keyboard, use the 'shiftkey?'
  function. For example:

    // test if the left or right <shift> keys are down
    if shiftkey? then
      .
      .
    end

    // test if scroll-lock is ON
    if shiftkey? 10h then
      .
      .
    end


  The following is a complete list of the keyboard functions:

    builtin functions:
      enhancedkbd    // enable or disable the enhanced keyboard keys
      getkey         // wait for a key and return a keycode
      getkeycode     // get a keycode for keyname
      getkeyname     // get a keyname for a keycode
      inheritkeys    // enable or disable keyboard event inheritance
      keyhit?        // test if a key was pressed
      queuekey       // push keycode(s) onto the event queue
      sendkey        // execute keycode(s) immediately
      shiftkey?      // test the shift key state

    extension functions:
      askrepkey      // prompt to repeat a key or keys
      prefix         // generate multi-key events


  The Mouse
  ─────────
  Several functions are provided to control the operation of the mouse
  within the editor. To use the mouse, a DOS mouse driver must have been
  successfully installed before the editor is started.

  In order for mouse events to be processed on the event queue, the
  mouse must be initialized with the 'openmouse' function when the
  editor is started. The 'closemouse' function should be called when
  exiting the editor:

    openmouse
      .
      .
      .
    closemouse

  If the mouse is successfully opened, and the mouse is moved or mouse
  buttons are clicked, the editor will call a user-defined function
  associated with the mouse event in the current event object. For
  example:

    // respond to a left mouse button click
    function <lbutton>
      say "you pressed the left mouse button"
    end

  The event-handling function names for mouse events (such as <lbutton>,
  <lbuttonup>, etc.) are predefined within the editor (see Appendix B:
  Mouse Event Names).

  The coordinates of the mouse pointer on the virtual screen can be
  obtained from the 'getmousex' and 'getmousey' functions. For example:

    // respond to a left mouse button click
    function <lbutton>
      say "Mouse x coordinate is: " + getmousex +
          "Mouse y coordinate is: " + getmousey
    end

  To find out what window 'region' the mouse pointer is located in, use
  the 'getregion' function:

    // respond to a left mouse button click
    function <lbutton>
      case getregion
        when  0  say "not in the window"
        when  1  say "client area"
        when 11  say "north title bar"
        otherwise say "other window region"
      end
    end

  The 'virtocol' and 'virtorow' functions are useful for determining the
  buffer column and row where the mouse pointer is located. For example:

    // respond to a left mouse button click
    function <lbutton>
      say "you clicked on column " + (virtocol (getmousex)) +
          ", row " +                 (virtorow (getmousey))
    end

  To find out if a mouse button is being held down, use the 'button?'
  function:

    if button? 2h then  // is the right mouse button down?
      .
      .
    end


  The following is a complete list of the mouse functions:

    builtin functions:
      button?        // test the mouse button state
      closemouse     // disable the mouse
      getmousex      // get the mouse virtual X coordinate
      getmousey      // get the mouse virtual Y coordinate
      getregion      // get the window region at the mouse position
      hidemouse      // hide the mouse cursor
      mousepos       // change the mouse pointer position
      mousesense     // change the mouse sensitivity
      openmouse      // enable the mouse
      showmouse      // show the mouse cursor
      virtocol       // convert a virtual X coordinate to a column
      virtorow       // convert a virtual Y coordinate to a row

    library functions:
      trackmouse     // move the cursor to the mouse pointer position


  Menus
  ─────
  Menus are windows (or window regions) which allow you to select an
  item from a list of choices. The selected item may be a number, a
  string, or even macro code to be executed when the item is selected.
  Menus can be defined and displayed by using macro language builtin
  functions and library functions.

  There are three basic types of menus: menu bars, pull-down menus
  (associated with menu bars), and independent popup menus.

  A menu bar can be associated with a window by using the 'menubar'
  statement. Up to five menu bars can be defined for each window. For
  example:

    menubar  '' 1
      item "&File"     "editFile"
      item "&Window"   "editWindow"
      item "&Block"    "editBlock"
      item "&Search"   "editSearch"
      item "F&old"     "editFold"
      item "&Edit"     "editEdit"
      item "&Clip"     "editClip"
      item "&Print"    "editPrint"
      item "Se&t"      "editSet"
      item "M&acro"    "editMacro"
      item "&Help"     "editHelp"
    end

  In the example above, a primary menu bar is defined for the current
  window (if a primary menu bar was already defined for the window, then
  it is replaced). The first argument after the 'item' keyword is the
  item description to appear on the menu bar. The '&' character
  indicates which character in the description is highlighted (and also
  which is the 'hot key' for that item). Specifying double ampersands
  '&&' indicates that the window control color should be used to
  highlight the item (for menu bars only).

  The second 'argument' after the 'item' keyword is the name of the
  pull-down menu to be activated when the item is selected. If desired,
  the second 'argument' can also be one or more macro language
  expressions to be evaluated in the current event object when the menu
  bar item is selected.

  To define a pull-down menu for a menu bar, or to define a popup menu,
  use the 'menu' statement. For example:

    menu  "editFile"
      item " &New                  <ctrl n>"  opennew
      item " &Open..                <alt e>"  askopen
      item " Open and &Insert..     <alt i>"  askinsert
      item " Open &Binary.."                  askopenb
      item " Open Las&t             <alt z>"  openlast
      item " &Rename..              <alt n>"  askname
      item " &Save                     <f3>"  save
      item " Sa&ve As.."                      asksaveas
      item "-"
      item " &File Manager..           <f4>"  open "*.*"
      item " Ne&xt               <ctrl del>"  nextfile
      item " &Prev               <ctrl ins>"  prevfile
      item " &List..                <alt ->"  filelist
      item "─"
      item " &Close                 <alt q>"  close
      item " Close &All             <alt x>"  closeall
      item " Sav&e and Close       <ctrl x>"  close "s"
      item " Save an&d Close All"             closeall "s"
      item "─"
      item " Abo&ut.."                        about
    end

  In the example above, a pull-down menu 'editFile' is defined for the
  first menu bar item 'File' in the previous menu bar example. Note that
  unlike 'menubar', the 'menu' statement will not replace an existing
  menu definition. Menus are actually buffers and must be destroyed with
  the 'destroybuf' function before the same menu name can be re-used. If
  the hyphen (-) character is specified in the item statement, then a
  dividing line is automatically generated for that item. Otherwise, the
  'item' keyword and arguments are identical to the 'menubar' statement.

  Submenus can be displayed by calling the 'submenu' function from a
  pull-down menu item. For example:

    menu  "editSet"
       .
      item " Word &Processing..             "   submenu "WordP"
       .
       .
    end

  In the example above, the submenu 'WordP' is displayed when the 'Word
  Processing' item is selected.

  Popup menus are defined with the 'menu' statement in exactly the same
  way as pull-down menus. However, whereas pull-down menus are
  automatically displayed when a menu bar item is selected, popup menus
  must be displayed with the library function 'popup'. For example:

    // displays the menu 'editFile' in a popup window
    popup "editFile"

  A menu title, width, and height can also be specified with the 'popup'
  function:

    popup "mymenu" "Menu Title" 25 10
      // displays the menu 'mymenu' with the title 'Menu Title',
      //   width 25, and height 10

  The 'popup' function returns the result of evaluating the macro
  expression associated with the selected menu item.

  The 'popup' function can also be used to display ordinary buffers in a
  popup menu by specifying the bufferid as a menu name. For example:

    buffer = loadbuf "file.txt"    // load a file into a buffer
    if buffer then
      popup buffer "Menu Title"    // display it in a popup menu
    end

  In this case, the 'popup' function returns the line selected in the
  buffer.


  The following is a complete list of the menu statements and functions:

    statements:
      menu         // define a pull-down or popup menu
      menubar      // define a menu bar for a window

    builtin functions:
      getmenu      // get menu information
      getmenubar   // get menu bar information
      hilitebar    // highlight menu bar item

    library functions:
      gotobar      // highlight a menu bar item
      gotobar2     // highlight a toolbar or drive menu item
      gotomenu     // display a pull-down menu
      popup        // display a popup menu
      submenu      // display a submenu


  The Desktop
  ───────────
  The editor provides several functions for saving and restoring the
  window layout on the screen. This layout is referred to as the
  'desktop'. The 'current desktop' refers to an internal representation
  of a desktop used by these functions.

  To save the desktop to a file, use the 'currdesk' and 'savedesk'
  functions:

    // set the 'current desktop' to the window layout on the screen
    currdesk

    // save the current desktop to C:\DESKTOP.BIN
    savedesk "c:\\desktop.bin"

  The 'opendesk' and 'restoredesk' functions can restore a previously
  saved desktop:

    // set the 'current desktop' to the desktop saved in C:\DESKTOP.BIN
    opendesk "c:\\desktop.bin"

    // set the window layout on the screen to the current desktop
    restoredesk


  The following is a complete list of the desktop functions:

    library functions:
      begdesk       // mark the beginning of the current desktop
      currdesk      // set the current desktop to the window layout
      enddesk       // mark the end of the current desktop
      opendesk      // load a desktop and make it the current desktop
      openhistory   // load history buffers and the current desktop
      restoredesk   // set the window layout to the current desktop
      savedesk      // save the current desktop to a file
      savehistory   // save all history buffers and the current desktop


  Prompts and Dialog Boxes
  ────────────────────────
  In addition to the menus, the editor provides several useful library
  and extension functions which allow you to obtain input from the user,
  and to display messages.

  To display a simple message on the main window title bar, use the
  'say' function:

    say "Hello World!"

  The message will remain on the title bar until the title bar or status
  line is updated.

  To display a message in a message box, use the 'msgbox' and 'shortbox'
  functions:

    // display a simple message box with an 'Ok' button
    msgbox "Hello World!" "Optional Title"

    // display a simple message box without an 'Ok' button
    shortbox "Hello World!"

  The 'okbox' and 'yncbox' functions can be used to display an Ok-Cancel
  or a Yes-No-Cancel message box. These functions return the text of the
  selected button, or null if nothing was selected:

    if (okbox "Delete the file?") == 'Ok' then
      deletefile file
    end

    case yncbox "Save before exiting?" "Sample Title"
      when 'Yes'
        // <save and exit>
      when 'No'
        // <exit>
      otherwise
        // <do nothing>
    end

  To prompt the user for a string, use the 'ask' function. The 'ask'
  function returns the string entered, or null if the prompt was
  cancelled. If a 'history bufferid' is specified, prompt history is
  available (and also recorded) within the prompt. For example:

    // prompt the user for a string
    string = ask "Enter a string"
    if string then
      say "you entered: " + string
    end

    // prompt the user for a string, using the history buffer "_load",
    // ..and initialize the prompt with the string 'c:\file.txt'
    ask "Enter a string" "_load" "c:\\file.txt"

  Note that when the user is working within a prompt generated with the
  'ask' function, the 'prompt' object is the current object. Thus, you
  can customize the behaviour of a prompt by specifying your own
  keyboard and mouse event-handling functions within the 'prompt'
  object.

  To prompt the user with a simple file selection picklist, use the
  'askfile' or 'picklist' functions. These functions return the file
  name (fully qualified) which was selected:

    file = picklist "*.*"
    if file then
      open file
      .
      .
    end


  The following is a complete list of the prompt and dialog box
  functions:

    library functions:
      about         // display an about dialog box
      ask           // prompt the user for a string
      askfile       // display a file selection picklist
      askprint      // display a print settings dialog box
      finddlg       // display a find dialog box
      msgbox        // display a message in a window
      okbox         // display an Ok-Cancel message box
      repldlg       // display a replace dialog box
      say           // display a message on the window title bar
      scandlg       // display a scan dialog box
      shortbox      // display a message box without an 'Ok' button
      yncbox        // display a Yes-No-Cancel message box

    extension functions:
      asciilist     // display an ASCII chart (with char entry)
      askrac        // replace/append/cancel popup menu
      askbinary     // binary line length prompt
      askc          // generic prompt to change a config variable
      askcomplete   // filename completion within an open prompt
      askdelim      // default line delimiter prompt
      asklmarg      // left margin prompt
      askprompt     // change the prompt style
      askprthdr     // change the print header/footer
      askrmarg      // right margin prompt
      asktabv       // variable tabs prompt
      asktabw       // tabwidth prompt
      askx          // generic prompt (with command execution)
      picklist      // display a file selection picklist


  Prompt History
  ──────────────
  Prompt history is available within prompts created by the function
  'ask' when a 'history bufferid' is specified. Prompt history is also
  available in the edit controls of some dialog boxes (finddlg, repldlg,
  and scandlg).

  The 'nexthist' and 'prevhist' functions are used to retrieve the next
  and previous history strings from within a prompt window:

    object prompt
      key <up>      prevhist
      key <down>    nexthist
       .
       .

  To display a popup menu of all the history strings available in the
  the current prompt window, use the 'askhistory' function:

    object prompt
      key <pgup>    askhistory
       .
       .

  The 'addhistory' function can be used to add a string to a specific
  history buffer. The history buffer is created if it does not exist.
  For example:

    // adds C:\FILE.TXT to the history buffer '_load'
    addhistory "_load" "C:\\FILE.TXT"

  The following history buffer names are used by the editor library:

    _find - search/replace for multi-string prompts
    _load - fully qualified file names (loading, saving, etc.)
    _desk - the current desktop

  The following is a complete list of the prompt history functions
  available in the editor library (LIB.X):

    addhistory    // add a string to a history buffer
    askhistory    // display a history menu for the current prompt
    gethistname   // get the history buffer for the current prompt
    gethiststr    // get the most recent string in a history buffer
    nexthist      // display the next history string in prompt
    openhistory   // load history buffers and the current desktop
    pophistory    // display a popup history menu
    prevhist      // display the previous history string in prompt
    savehistory   // save all history buffers and the current desktop


  Primary Editing Functions
  ─────────────────────────
  The editor library (LIB.X) and editor extensions (EXT.AML) contain a
  few important and commonly-used high-level editing functions which are
  discussed briefly here.

  To open a file and create a new edit window, or to open a new file
  manager window, use the 'open' function. For example:

    open "myfile.txt"        // edit the file 'myfile.txt'
    open "myfile.txt" 'b'    // edit 'myfile.txt' in binary mode
    open "myfile.txt" 'i'    // insert 'myfile.txt' at the cursor
    open "*.txt" 'z'         // open a maximized file manager window
                             //   displaying the files '*.txt'

  The 'openbuf' function can be used to display an existing buffer in an
  edit window. A fully qualified file name should be associated with the
  buffer by using the 'setbufname' builtin function. For example:

    prevbuf = getbufname
    buffer = createbuf ''
               "first line"
               "second line"
    if buffer then
      setbufname (qualify "newfile.txt" prevbuf)
      openbuf buffer
    end

  To save a file in the current edit window, use the 'save' function:

    save                 // save the file in the current edit window
    save "c:\\file.txt"  // save the file as 'c:\file.txt'

  To close the current edit window or file manager window, use the
  'close' function:

    close       // close the current window
    close 's'   // save and close the current edit window


  The following is a complete list of the primary editing functions:

    library functions:
      close       // close the current edit or file manager window
      filelist    // display a popup menu of open buffers
      nextfile    // display the next buffer in the current window
      open        // open a new edit or file manager window
      openbuf     // display a buffer in an edit window
      opennew     // open a new edit window with an empty buffer
      prevfile    // display the previous buffer in the current window
      reopen      // refresh the current edit or file manager window
      save        // save the buffer in the current edit window
      setname     // rename the current edit window and buffer

    extension functions:
      askasave    // prompt to set the autosave time interval
      askinsert   // prompt to insert a file at the cursor
      askname     // prompt to change the current file name
      askopen     // prompt to open an edit or file manager window
      askopenb    // prompt to open a file in binary mode
      asksaveas   // prompt to save the current file under a new name
      autosave    // set the autosave time interval
      close       // close the current window (higher level)
      closeall    // close all windows
      opencfg     // open an AML configuration file
      openlast    // open the last file closed
      openword    // open the filename at the cursor
      print       // print current file or marked block
      printfile   // print a file on disk
      printstr    // send a string to the printer
      quickref    // display function reference or quick reference


  DOS Shell Functions
  ───────────────────
  The editor provides several functions for executing DOS programs and
  batch files from within the editor. All of these functions are based
  on the low-level builtin function 'exec'. For example:

    exec "C:\\RUNME.EXE" 'c'
      // clear the screen and execute "c:\runme.exe"

    exec "C:\\RUNME.EXE" 'k'
      // execute "c:\runme.exe" (without clearing the screen),
      // and prompt the user with a keypress to return

  The 'os' function changes the current path to the path of the current
  edit or file manager window before executing the program, and restores
  the current path after executing the program:

    os "C:\\RUNME.EXE" 'c'
      // clear the screen and execute "c:\runme.exe", changing
      // the current path to the window path

  The 'shell' function looks for the COMSPEC environment variable to
  find the location of COMMAND.COM, and then executes COMMAND.COM.

  Unlike the 'exec' or 'os' functions, the function 'run' will execute
  DOS commands, programs, and batch files as they would be entered on
  the DOS command line. It will also search the DOS 'PATH' environment
  variable if necessary. For example:

    run "runme" 'c'  // clear the screen and execute 'c:\runme.exe'
    run "dir" "ck"   // execute the DOS 'dir' command


  The following is a complete list of the DOS Shell functions:

    builtin functions:
      exec       // execute a DOS program (low level)

    extension functions:
      askrun     // prompt to execute a DOS command
      askruncap  // prompt to capture DOS command output
      os         // execute a DOS program (change and restore path)
      run        // execute a DOS command
      runcap     // execute a DOS command and capture output
      shell      // shell to DOS


  Key Macro Functions
  ───────────────────
  The editor provides several library and extension functions for
  manipulating 'key macros'. Key macros are recorded sequences of
  keystrokes which can be played back at a later time.

  To start and stop recording keystrokes, use the 'setting' function to
  change the window 'record mode':

    setting 'R' ON      // start recording keystrokes (record mode ON)
    setting 'R' OFF     // stop recording keystrokes (record mode OFF)
    setting 'R' TOGGLE  // toggle the window record mode

  A key macro that has just been recorded is called the 'scrap' macro.
  The 'assignkey' function can be used to assign the scrap macro to a
  key:

    assignkey   // prompts for a key assignment

  Both the 'scrap' macro and key-assigned key macros can be executed
  with the 'playkey' function:

    playkey            // play the scrap key macro
    playkey <ctrl m>   // play the key macro assigned to <ctrl m>

  The 'openkey' and 'savekey' functions are used to save and load all
  key macros (both the scrap macro and key-assigned macros):

    savekey "c:\\keymacs.mac"      // save all key macros
    openkey "c:\\keymacs.mac"      // load saved key macros


  The following is a complete list of the key macro functions:

    builtin functions:
      playing?       // test if a key macro is currently playing

    library functions:
      assignkey      // assign the scrap macro to a key
      erasekey       // erase the scrap macro or all key macros
      openkey        // load key macros in a file
      playkey        // execute a key macro
      savekey        // save all key macros to a file
      setting        // turn record mode ON and OFF

    extension functions:
      askopenkey     // prompt to open a key macro file
      asksavekey     // prompt to save current key macros
      erasekey2      // erase key macros (with messages)
      openkey2       // open a key macro file (with messages)
      play           // play the current scrap macro
      record         // toggle the record setting


  File Manager Functions
  ──────────────────────
  Several library and extension functions are provided for interfacing
  with the file manager.

  To refresh the contents of the current file manager window, use the
  'reopen' function:

    reopen   // refresh the file manager window

  To retrieve the fully qualified file or directory name at the current
  line in a file manager window, use the 'getffile' function:

    deletefile (getffile)   // delete the file at the current line
    reopen                  // refresh the file manager window

  To execute a user-defined function for all marked files in the file
  manager, use the 'fdomark' function. For example:

    fdomark "chgfileattr" attribute

  In the above example, the builtin function 'chgfileattr' is called for
  each marked file, passing the filename as the first argument and the
  value of the variable 'attribute' as the second argument.

  The following is a complete list of the file manager functions:

    library functions:
      fdobrk     // break out of the 'fdomark' function
      fdomark    // execute a function for all marked files
      fmark      // mark or unmark files
      fmark?     // test if files are marked
      fscanstr   // get the scan string for a file manager window
      fsort      // sort files
      ftype?     // test file manager window type
      fup        // display the parent directory
      getffile   // get the filespec at the current line
      openf      // open files (low level)

    extension functions:
      fattr      // change the attributes of a file or marked files
      fcopy      // copy a file or marked files
      fdelete    // delete a file or marked files
      fmkdir     // create a new directory
      fmove      // move a file or marked files
      fopen      // open a file or marked files
      fprint     // print a file or marked files
      frename    // rename a file or directory
      frun       // execute a file
      ftouch     // update date/time of a file or marked files


  On-Event Functions
  ──────────────────
  To provide for an even higher degree of customization, the editor
  calls several event functions that 'notify' you when an important
  internal event has occurred, such as starting the editor, opening a
  file, etc. Using the macro language, you can write event handling
  functions which respond to these events.

  The 'onentry' and 'onexit' events are generated when an edit session
  is started and ended. Functions which respond to these events
  typically perform some initialization or cleanup tasks. For example:

    function onentry
      // 'onentry' in EXT.AML performs the following initializations:
      //   - open prompt and window history
      //   - open any command-line filespecs passed to this function
      //   - still no windows open? then do bootoptions
      //   - mouse setup
      //   - open key macro files
    end

    function onexit
      // 'onexit' in EXT.AML performs the following cleanup tasks:
      //   - save prompt and window history
      //   - save key macros if record occurred
    end

  The 'onopen' event is generated when a new file is loaded or a file
  manager window is created. Functions which respond to this event can
  perform a variety of customizations, such as setting the window object
  class, altering the window settings and the tab width based on the
  file extension, expanding tabs, changing the menus, or almost anything
  else you can think of. For example:

    object edit
       .
       .
      // an edit window has been opened..
      function onopen
         .
         .
        // if the window settings are not remembered from a previous
        // session, set them based on the file extension:
        if not getsettings then
          case getext (getbufname)

            // for C or C++ files, turn on syntax highlighting,
            // autoindent, undo, and file backup
            when ".C", ".CPP". ".H"
              setting "XAUB" ON

            // for documents, turn on live word wrap, text translation,
            // autoindent, undo, and file backup
            when ".TXT", ".DOC"
              setting "LTAUB" ON

            // for all other extensions, use the configuration default
            otherwise
              setting _DefaultSet ON
          end
        end
      end

  The 'pass' builtin function can be used from within an on-event
  function to 'pass on' the event notification to the same on-event
  function in other objects.


  The following is a complete list of all the 'onevent' functions:

    builtin functions:
      oncompiling    // called while compiling a file
      onloading      // called while loading a file
      onprinting     // called while printing a file
      onsaving       // called while saving a file

    library functions:
      onalarm        // called to sound the PC speaker
      onclose        // called before closing a file or fmgr window
      oncomment      // returns language comments for a filename
      onentry        // called after starting the editor
      onexit         // called before exiting the editor
      onfocus        // called after switching to another file or window
      onfound        // called after a string is found
      onhotkey       // called after a filelist hotkey char is entered
      onopen         // called after loading a new file or fmgr window
      onscanning     // called while scanning files
      onsyntax       // returns a syntax object for a filename

    extension functions:
      onsave         // called before a file is saved


  Library Object Hierarchies
  ──────────────────────────
  In order to better understand the windowing behaviour of the editor,
  it is important to understand how some of the objects defined in the
  editor library (LIB.X) are organized.

  The editor library generally associates the objects it defines with
  one or more window types. For example, the object 'edit' is associated
  with edit windows, while the object 'edit_fmgr' is associated with
  both edit windows and file manager windows. This means that the object
  'edit' contains functions and variables that are only relevant to edit
  windows, while the object 'edit_fmgr' contains functions and variables
  which apply to both edit and file manager windows.

  This distinction also applies to event-handling functions. For example
  in the Aurora KBD.AML file, the <alt e> key performs the same action
  (display an open prompt) in both edit windows and file manager
  windows. Therefore, <alt e> is defined only once in the 'edit_fmgr'
  object, avoiding duplicate definitions in the 'edit' and 'fmgr'
  objects. Note that in order for this to work, the 'edit' object must
  be descended from the 'edit_fmgr' object. Thus when a key is pressed
  in an edit window, and the key definition is not found in the 'edit'
  object, the 'edit_fmgr' object is searched for the key definition.

  These are some of the object statements used to define objects and
  object hierarchies for editor windows in the editor library (LIB.X):

    object  a         (prf                  )
    object  mon       (a                    )
    object  win       (a mon                )
    object  prompt    (win                  )
    object  edit_fmgr (a win                )
    object  fmgr      (a edit_fmgr          )
    object  edit      (a prompt edit_fmgr   )

  The following is a partial graphical representation of the object
  hierarchy:

             prf
              │
              a                  // parent objects
              ├─── mon
       ┌──── win ────┐
    prompt         edit_fmgr
       └──┬──────────┘  │        // child objects
         edit          fmgr


  The following list shows the window types associated with each object:

    a          - all windows
    mon        - all windows
    win        - movable or sizable windows
    prompt     - edit windows, prompt windows, and edit controls
    edit_fmgr  - edit and file manager windows
    fmgr       - file manager windows
    edit       - edit windows



  Appendix A:  Key Event Names
  ────────────────────────────
  The following table lists the pre-defined keyboard event names
  generated or recognized by the editor. Enhanced keyboard keys are
  followed by an asterisk (*). Keyboard event names may be entered in
  mixed case.


  Normal Keys         Alt               Ctrl               Shift
  ───────────         ───               ────               ─────

  // non-function (typeable) keys
  // (arguments: 1=character, 2=keycode)
  <char>

  // any shiftkey pressed or released
  // (arguments: 1=old shift state, 2=new shift state)
  <shiftkey>

  // undefined or unrecognized keyboard event
  // (arguments: 1=keycode)
  <otherkey>


  // (arguments for all other keys: 1=keycode)

  // numeric keys
                      <alt 0>
                      <alt 1>
                      <alt 2>           <ctrl 2>
                      <alt 3>
                      <alt 4>
                      <alt 5>
                      <alt 6>           <ctrl 6>
                      <alt 7>
                      <alt 8>
                      <alt 9>

  // alphabetic keys
                      <alt a>           <ctrl a>
                      <alt b>           <ctrl b>
                      <alt c>           <ctrl c>
                      <alt d>           <ctrl d>
                      <alt e>           <ctrl e>
                      <alt f>           <ctrl f>
                      <alt g>           <ctrl g>
                      <alt h>           <ctrl h>
                      <alt i>           <ctrl i>
                      <alt j>           <ctrl j>
                      <alt k>           <ctrl k>
                      <alt l>           <ctrl l>
                      <alt m>           <ctrl m>
                      <alt n>           <ctrl n>
                      <alt o>           <ctrl o>
                      <alt p>           <ctrl p>
                      <alt q>           <ctrl q>
                      <alt r>           <ctrl r>
                      <alt s>           <ctrl s>
                      <alt t>           <ctrl t>
                      <alt u>           <ctrl u>
                      <alt v>           <ctrl v>
                      <alt w>           <ctrl w>
                      <alt x>           <ctrl x>
                      <alt y>           <ctrl y>
                      <alt z>           <ctrl z>

  // non-alphanumeric
                      <alt '>*
                      <alt ,>*
                      <alt ->           <ctrl ->
                      <alt .>*
                      <alt />*
                      <alt ;>*
                      <alt =>
                      <alt [>*          <ctrl [>
                      <alt \>*          <ctrl \>
                      <alt ]>*          <ctrl ]>
                      <alt `>*

  // function keys
  <f1>                <alt f1>          <ctrl f1>          <shift f1>
  <f2>                <alt f2>          <ctrl f2>          <shift f2>
  <f3>                <alt f3>          <ctrl f3>          <shift f3>
  <f4>                <alt f4>          <ctrl f4>          <shift f4>
  <f5>                <alt f5>          <ctrl f5>          <shift f5>
  <f6>                <alt f6>          <ctrl f6>          <shift f6>
  <f7>                <alt f7>          <ctrl f7>          <shift f7>
  <f8>                <alt f8>          <ctrl f8>          <shift f8>
  <f9>                <alt f9>          <ctrl f9>          <shift f9>
  <f10>               <alt f10>         <ctrl f10>         <shift f10>
  <f11>*              <alt f11>*        <ctrl f11>*        <shift f11>*
  <f12>*              <alt f12>*        <ctrl f12>*        <shift f12>*

  // special keys
  <backspace>         <alt backspace>*  <ctrl backspace>
  <enter>             <alt enter>*      <ctrl enter>
  <esc>               <alt esc>*
                                        <ctrl prtsc>
  <tab>               <alt tab>*        <ctrl tab>*        <shift tab>

  // keypad keys
  <del>               <alt del>*        <ctrl del>*        <shift del>
  <down>              <alt down>*       <ctrl down>*       <shift down>
  <end>               <alt end>*        <ctrl end>         <shift end>
  <home>              <alt home>*       <ctrl home>        <shift home>
  <ins>               <alt ins>*        <ctrl ins>*        <shift ins>
  <left>              <alt left>*       <ctrl left>        <shift left>
  <pgdn>              <alt pgup>*       <ctrl pgup>        <shift pgup>
  <pgup>              <alt pgdn>*       <ctrl pgdn>        <shift pgdn>
  <right>             <alt right>*      <ctrl right>       <shift right>
  <up>                <alt up>*         <ctrl up>*         <shift up>
  <center>*                             <ctrl center>*     <shift center>

  // grey keypad keys
  <grey*>             <alt grey*>*      <ctrl grey*>*
  <grey+>             <alt grey+>*      <ctrl grey+>*
  <grey->             <alt grey->*      <ctrl grey->*
                      <alt grey/>*      <ctrl grey/>*
  <greyenter>         <alt greyenter>*  <ctrl greyenter>*



  Appendix B:  Mouse Event Names
  ──────────────────────────────
  The following table lists the pre-defined mouse event names generated
  or recognized by the editor. Mouse event names may be entered in mixed
  case.


  Name             Action
  ────             ──────
  <lbutton>        left button down
  <lbuttonup>      left button up
  <rbutton>        right button down
  <rbuttonup>      right button up
  <cbutton>        center button down
  <cbuttonup>      center button up

  <move>           mouse movement

  <ldouble>        left button double click
  <rdouble>        right button double click
  <cdouble>        center button double click

  <ltriple>        left button triple click
  <rtriple>        right button triple click
  <ctriple>        center button triple click

  <chord>          mouse chord